[Development] Documentation and Modularization

[Marc Mutz]

On Wednesday September 19 2012, Gladhorn Frederik wrote:
[...]
> Since we don't see a way to fix the modularized build of the docs without
> big issues (predictive links seem hard to get right and we couldn't show
> warnings about them easily), we propose to actually make use of a mixed
> approach to get the documentation for Qt 5.0 in shape (it's about time).
> For developers we want to keep the modular approach to make their lives
> easy and make it convenient to actually run qdoc. In order to generate the
> documentation used on the website/sdk etc we would use the monolithic
> approach. In order to not drown in warnings for links that could not be
> resolved, we would implement one feature in qdoc: "external" links. These
> will simply be ignored when running make docs in a module if they cannot be
> resolved. This gets rid of the warnings and since the marking as external
> is explicit. For the monolithic build of the docs on the other hand we'd
> warn about all missing links. The exact syntax for how an external link
> would look like needs to be figured out still. The best we came up with
> right now is prefixing links with "external_link::" which would work with
> \l external_link::QWidget::show() and \sa etc. Actually the prefix most
> certainly will look different, let's see what experiments with qdoc yield.
[...]

Doxygen uses "tag files" to store the link structure of a module, and, using 
them, can cross-link between modules in an iterative manner 
(http://www.stack.nl/~dimitri/doxygen/external.html for details):

1. Process all modules separately, yielding one tag file per module
2. Process each module again, providing all other module's tag files as input, 
after you have created all of them.

Using something like this, we could keep module documentation creation local 
to each module, while still allowing arbitrary cross-references (albeit using 
two passes if there are cyclic dependencies).

Plus points if the Doxygen's tag file format is used, so as to allow easy 
linking to Qt documentation with Doxygen-based projects (Doxygen used to be 
able to harvest a tag file from Qt's HTML docs, but at some Qt version this 
broke).

Thanks,
Marc

-- 
Marc Mutz <marc.mutz at kdab.com> | Senior Software Engineer
KDAB (Deutschland) GmbH & Co.KG, a KDAB Group Company
www.kdab.com || Germany +49-30-521325470 || Sweden (HQ) +46-563-540090
KDAB - Qt Experts - Platform-Independent Software Solutions