Generating Documentation From C++ Sources


Table of Contents

1. How does it work?
2. Status/TODO
3. Caveats
4. Example
A. Using gccxml and xalan
5. Links
6. Sponsoring
7. Thanks

Chapter 1.  How does it work?

The output of gccxml (a patched gcc-3.3 c++ frontend) is parsed, and the declaration nodes (for namespaces, classes, class-templates etc.), which contain source file and line number information, are stored in maps (dictionaries). Additionally a (simple) parser scans the c++ files for comments in "javadoc" format and tags these to the nodes. Finally, documentation in "docbook" format is created.

Chapter 2.  Status/TODO

Gathering the information from an xml output file, and collecting the comments from the c++ files already works. Formatting the output in docbook format is just at the beginning (help welcome). There are also a lot of other things to do: When multiple c++ source files are used, the output files created by gccxml must be merged (but i don't think that this will be a problem, since mangled names are unique)

Chapter 3.  Caveats

gccxml Only creates information for templates, if they are instantiated in the source files (since c++ compilers have to ignore templates, if they aren't instantiated (or at least gcc-3.3 is doing so, with gcc-3.4 i am not so sure)).

So one is forced to create dummy source files, in which the header files are included and the templates get instantiated. But on the other hand this is also a good check, if the templates are ok, and also a good regression test, so this doesn't bother me very much.

Chapter 4.  Example

C++ source files:

x1.cpp

h1.h

Output created by gccxml:

x1.xml

Docbook output created by cniffxx (well, as i said, formatting the output is just at the beginning:)):

x1_index.xml

ns_1.xml

ns_2.xml

(probably your browser resolves external entities, so when clicking on x1_index.xml you see all three files as one.)

Docbook output rendered into html:

x1_index.html

Appendix A.  Using gccxml and xalan

This is mainly a reminder for myself, pathnames reflect my local configuration.

Calling gccxml from the command line:

C:\NORBERT\cniffxx-cvs\sandbox\sax_test1\input>gccxml x1.cpp -fxml=x1.xml

Calling xalan from the command line:

C:\NORBERT\cniffxx-cvs\sandbox\sax_test1\output>xalan -v -o index.html index.xml c:/emacs/xml/stylesheets/docbook-xsl-1.67.2/html/docbook.xsl

Chapter 5.  Links

Project page with CVS, forum, etc.:

cniffxx Project page

Chapter 6.  Sponsoring

Financial help is welcome, since:

a) I could need a faster computer, using xml-tools written in java, like Xalan etc., is too slow on my machine (a bit out of date, using xalan-c now).

and

b) a nice, working documentation tool based on gccxml, might encourage the gccxml developers to actively maintain gccxml, or even encourage the gcc developers themselves to add some xml export feature to their c++ frontend (and, of course, some financial reward, would also increase my own motivation to work on this project (and speed it up)).

Support this project

Chapter 7.  Thanks

Thanks to SourceForge for supporting this project:

SourceForge.Net Logo