2007年2月9日星期五

doxygen parsing flow

http://www.stack.nl/~dimitri/doxygen/starting.html#extract_all

1. execute the special commands in documentation. the special commands are listed in:
http://www.stack.nl/~dimitri/doxygen/commands.html
the documentation is always specified by documentation block: http://www.stack.nl/~dimitri/doxygen/docblocks.html#specialblock
somtimes, it can be specified at other place:
http://www.stack.nl/~dimitri/doxygen/docblocks.html#structuralcommands

2. remove the line start by some whitespace followed by one or more asterisks(*) and then optionally more whitespace.

3. Keep all resulting blank lines to make documentation readable.

4. Create links.
1) for the words corresponding to documented class, execpt the words is preceded by a '%'.
2) for the members corresponding to some pattern, http://www.stack.nl/~dimitri/doxygen/autolink.html

5. Interpret HTML tags, http://www.stack.nl/~dimitri/doxygen/htmlcmds.html.

Tips:
.% can be used to despress the auto links for the words of ducumented class.
.It can be documented with documentation block or at other place.

doxygen examples

http://www.stack.nl/~dimitri/doxygen/results.html

five nice examples are listed there:
1. KDevelop API Documentation
http://kdevelop.org/HEAD/doc/api/html/
It is a beautiful documentation, I wonder how to generate it by doxygen. Till now, I only knew it is possible to modify the cofigure for doxygen, it still seems impossible for me to gernerate such a smart documentation.
Maybe we can start to look for the answer from here:
http://www.stack.nl/~dimitri/doxygen/starting.html#extract_all
then, devote ourselves to the configuration for more detail, pay more attention to the HTML related options, such as HTML_HEADER, HTML_FOOTER and HTML_STYLESHEET:
http://www.stack.nl/~dimitri/doxygen/config.html
a friendly GUI front-end Doxywizard might be very useful:
http://www.stack.nl/~dimitri/doxygen/doxywizard_usage.html

2. The Xerces C++ Documentation
http://xml.apache.org/xerces-c/apiDocs/index.html
This example customize the web style, but do not contains more content in main page.

3. D-Bus documentation
http://dbus.freedesktop.org/doc/api/html/index.html
4. Yahoo Music Engine
http://plugins.yme.music.yahoo.com/plugins/docs/
5. IBM's International Component for Unicode
http://icu.sourceforge.net/apiref/icu4c/

These three examples all customize the main pages and show some extra item on the navigation bar. The fourth one also customize footer .

I guess that the main page that doxygen grenerates for some project might depend on the comments in the project. Here is the good start point to start document the source :
http://xml.apache.org/xerces-c/apiDocs/index.html

Tips:
.how to set the configuration to customize the html page?
.how to document for the main page or overview page?