[Development] Documentation and Modularization

[Saether Jan-Arve]

Actually, I have tried using tag files (or rather, qdocs .index files, which I guess is a superset of "tag files" in the semantic sense).

This works in principle, but it needs some additional changes to qdoc and how the makefiles are generated (since its two-pass).
We can go down that route later, since it has some interesting side-effects, such as faster, parallelized generation of docs (well, in theory at least), and a more harmonized way of building the docs. (the monolithic make docs will be able to use the modular make docs). These are not super-important for Qt 5.0 though.

Jan Arve

________________________________________
Fra: development-bounces+jan-arve.saether=digia.com at qt-project.org [development-bounces+jan-arve.saether=digia.com at qt-project.org] på vegne av Marc Mutz [marc.mutz at kdab.com]
Sendt: 19. september 2012 15:23
To: development at qt-project.org
Emne: Re: [Development] Documentation and Modularization

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
_______________________________________________
Development mailing list
Development at qt-project.org
http://lists.qt-project.org/mailman/listinfo/development