[Development] Documentation and Modularization
I'm not sure if we want to go down this route (doxygen), but it seems an option to me. We have discussed it many times. The management decision has always been to proceed with qdoc. I don't feel strongly either way, but if I'm asked I would say we should stay with qdoc and just move qdoc gradually toward doxygen. The qdoc index file was originally meant to allow a customer to link his documentation to the Qt documentation, so we generated the Qt documentation with qdoc, and as a byproduct, qdoc produced qt.index, which is then loaded with the customers sourses when qdoc generates the customer's documentation. So, functionally, qt.index is like a doxygen tag file, but I don't like the implementation, so I think we should add the doxygen tag file functionality to qdoc. qdoc already has something called a tag file, but this is for a different purpose. I think we might not need it anymore. Earlier I proposed getting qdoc to output a target file, which I suppose is the same as the doxygen tag file. martin ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Documentation and Modularization
23.09.2012, 14:25, Frederik Gladhorn gladh...@kde.org: Hi, since we were discussing how to maintain QDoc and how to fix issues, I poked at doxygen again. I also sent a mail to it's maintainer who responded quickly and friendly. I'm not sure if we want to go down this route, but it seems an option to me. It means a lot of work, but so does maintaining qdoc and extending it (does anyone feel like adding template support there?). Below are my initial findings (looking at qtcore only). Feel free to correct me or add your experience with doxygen. Cheers Frederik Big issues: - QML - No support for tables? \table \header \row ... Doxygen supports HTML tables. Tag Files: see Linking to external documentation while possible to have circular dependencies this requires re-runs of doxygen afaict (check mail from Marc Mutz on devel mailing list, this approach favors incremental documentation builds) as all solutions this means running the tool twice, there is no explicit switch to only generate tags/docs as far as I can see Open Questions: * inheritance What's the problem? Doxygen adds section Inherits for inherited classes. \reimp ? * snippet markers need begin and end? * no support for \section1 \section2 etc in class documentation, only in pages (\section \subsection ...) * xml output is different from dita I think, I didn't look into this and I don't think dita is required any more * is the license a problem? I'd say no: Doxygen is GPL, but: Documents produced by doxygen are derivative works derived from the input used in their production; they are not affected by this license. * is speed an issue? is it slower/faster than qdoc? I don't think it matters that much, but we'd like to have the make docs step run when building Qt by default... Work needed in doxygen config: * generally macro expansion needs fine-tuning \macro ? there is preprocessing leading to macro expansion (optional) with PREDEFINED it's prossible to replace macros with different source code (eg nothing) \l - see custom commands - should work \threadsave \reentrant \tt \b section labels \section1 seems to not work \module - \defgroup \inmodule - \ingroup \since needs to expand to boiler plate text Work needed on Qt documentation: * enums - inline value documentation \value - enums in header Todo: * write config files * integrate with build system (two runs during build?) * integrate with stylesheets and adopt html templates etc Nice stuff: + output formats + searching client and server side + graphs, inheritance diagrams + lists in bb style possible (less typing) + seemingly better template support (needs checking) + automatically documents typedefs (?) + link to source files possible + inline enum documentation + maintainer reacted to mail within a day and was happy about potential qml contributions ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development -- Regards, Konstantin ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Documentation and Modularization
On Monday 24. September 2012 13.36.10 Konstantin Tokarev wrote: 23.09.2012, 14:25, Frederik Gladhorn gladh...@kde.org: Hi, since we were discussing how to maintain QDoc and how to fix issues, I poked at doxygen again. I also sent a mail to it's maintainer who responded quickly and friendly. I'm not sure if we want to go down this route, but it seems an option to me. It means a lot of work, but so does maintaining qdoc and extending it (does anyone feel like adding template support there?). Below are my initial findings (looking at qtcore only). Feel free to correct me or add your experience with doxygen. Cheers Frederik Big issues: - QML - No support for tables? \table \header \row ... Doxygen supports HTML tables. Ok, sounds good. Thanks for pointing that out. Open Questions: * inheritance What's the problem? Doxygen adds section Inherits for inherited classes. I didn't check, but it produces different output for class interitance. I think we used to hide some inheritance (iirc QAtomicInt or some class like that) when it was of a private base class. I don't think this would be a blocker though. Mind that I just glanced at it out of curiosity. Nobody has seriously considered switching from qmake and I think we have enough issues to fight. It's just something we might discuss for longer term. Greetings Frederik ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Documentation and Modularization
Hi, since we were discussing how to maintain QDoc and how to fix issues, I poked at doxygen again. I also sent a mail to it's maintainer who responded quickly and friendly. I'm not sure if we want to go down this route, but it seems an option to me. It means a lot of work, but so does maintaining qdoc and extending it (does anyone feel like adding template support there?). Below are my initial findings (looking at qtcore only). Feel free to correct me or add your experience with doxygen. Cheers Frederik Big issues: - QML - No support for tables? \table \header \row ... Tag Files: see Linking to external documentation while possible to have circular dependencies this requires re-runs of doxygen afaict (check mail from Marc Mutz on devel mailing list, this approach favors incremental documentation builds) as all solutions this means running the tool twice, there is no explicit switch to only generate tags/docs as far as I can see Open Questions: * inheritance \reimp ? * snippet markers need begin and end? * no support for \section1 \section2 etc in class documentation, only in pages (\section \subsection ...) * xml output is different from dita I think, I didn't look into this and I don't think dita is required any more * is the license a problem? I'd say no: Doxygen is GPL, but: Documents produced by doxygen are derivative works derived from the input used in their production; they are not affected by this license. * is speed an issue? is it slower/faster than qdoc? I don't think it matters that much, but we'd like to have the make docs step run when building Qt by default... Work needed in doxygen config: * generally macro expansion needs fine-tuning \macro ? there is preprocessing leading to macro expansion (optional) with PREDEFINED it's prossible to replace macros with different source code (eg nothing) \l - see custom commands - should work \threadsave \reentrant \tt \b section labels \section1 seems to not work \module - \defgroup \inmodule - \ingroup \since needs to expand to boiler plate text Work needed on Qt documentation: * enums - inline value documentation \value - enums in header Todo: * write config files * integrate with build system (two runs during build?) * integrate with stylesheets and adopt html templates etc Nice stuff: + output formats + searching client and server side + graphs, inheritance diagrams + lists in bb style possible (less typing) + seemingly better template support (needs checking) + automatically documents typedefs (?) + link to source files possible + inline enum documentation + maintainer reacted to mail within a day and was happy about potential qml contributions ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Documentation and Modularization
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@qt-project.org [development-bounces+jan-arve.saether=digia@qt-project.org] p#229; vegne av Marc Mutz [marc.m...@kdab.com] Sendt: 19. september 2012 15:23 To: development@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.m...@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@qt-project.org http://lists.qt-project.org/mailman/listinfo/development ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
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.m...@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@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
