23.09.2012, 14:25, "Frederik Gladhorn" <[email protected]>: > 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 > [email protected] > http://lists.qt-project.org/mailman/listinfo/development -- Regards, Konstantin _______________________________________________ Development mailing list [email protected] http://lists.qt-project.org/mailman/listinfo/development
