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: [email protected] [[email protected]] på vegne av Marc Mutz [[email protected]] Sendt: 19. september 2012 15:23 To: [email protected] 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 <[email protected]> | 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 [email protected] http://lists.qt-project.org/mailman/listinfo/development _______________________________________________ Development mailing list [email protected] http://lists.qt-project.org/mailman/listinfo/development
