[Development] Documentation and Modularization

[Frederik Gladhorn]

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