[Development] Documentation and Modularization

[Konstantin Tokarev]

23.09.2012, 14:25, "Frederik Gladhorn" <gladhorn at 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 at qt-project.org
> http://lists.qt-project.org/mailman/listinfo/development

-- 
Regards,
Konstantin