KDOC -- C++ Class Documentation Tool

Sirtaj S. Kang (taj@kde.org), Torben Weis (weis@kde.org)

Copyright (c) 1997

(This package includes a modified version of Sriram Srinivasan's perl AST module)

Distributed under the GNU Public License

KDOC is a C++ class documentation extraction tool, initially written for the specific purpose of generating documentation for the KDE libraries.

KDOC extracts specially formatted documentation and information about your classes from the class' header files, and generates cross-referenced HTML, LaTeX or man pages from it.

KDOC allows groups of classes to be formed into "libraries" and documentation from separate libraries can be very easily cross-referenced.

For a sample of KDOC's HTML output, see http://www.ph.unimelb.edu.au/~ssk/kde/srcdoc/kdeui/heir.html

Features

Why didn't we use cocoon or DOC++?

Writing the source documentation

The format for the comments is very similar to that of the javadoc package, which is a part of the Java Development Kit.

In general, a doc comment is a C comment that immediately precedes a class, method, constant or property declaration. It takes the form:


/**
* Documentation goes here
*/
class KMyClass {
	...

Note the double asterisk at the start of the comment. This is what differentiates a doc comment from a normal comment.

Preceding asterisks on each line are ignored.

The documentation is a mixture of:

The valid tags for each type of source code entity are:

Examples of doc comments

See the file example.h. This is the same example I have up on the KDE Developers' Centre.

Other sources of examples:

Generating the documentation

When you process a set of C++ headers with KDOC it creates

You need a place to put the kdoc files and to search for them if you are cross-referencing from another library. You can specify this with the -L flag.

The default is the current directory, or $KDOCLIBS if it is set.

NOTE: The included qt2kdoc program can generate qt.kdoc from the classes.html file that comes with Qt's documentation.

Example:

The headers "*.h" in the directory ~/baseline/kdelibs/kdecore make up a library called kdecore. I wish to generate HTML documentation for this library and store in in $HOME/web/kdecore, which can be accessed by the URL

http://www/~ssk/kdecore/

I also want to include references to the Qt toolkit, for which I have a qt.kdoc file.


cd ~/baseline/kdelibs/kdecore
kdoc -H -d $HOME/web/kdecore -u "http://www/~ssk/kdecore/" kdecore *.h -lqt

That's all there is to it. kdoc will create up to one level of missing directories in the output path (ie it would have created "$HOME/web/kdecore/" if "$HOME/web/" existed).

See kdoc -h for a synopsis of kdoc's options. Please forgive this haphazard documentation. I am in the (slow, painful) process of writing an extended manual, but wanted to get this package out quickly. Expect lots of updates.


Sirtaj S. Kang (taj@.kde.org), Tue Dec 16 14:32:15 EST 1997.