KDOC -- C++ and IDL Class Documentation Tool

Copyright (c) 1999

Be warned that this is still under development, but it is already better than KDOC 1 for use with HTML and texinfo.

Getting KDOC 1

What is KDOC?

KDOC is a C++ and IDL interface documentation 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 or IDL 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/hier.html

This application is distributed under the GNU Public License. It is inspired by a program of the same named written by Torben Weis <weis@kde.org> in 1997. It contains an AST module written by Sriram Srinivasan.

Features

• Generates HTML, Man-page and LaTeX output.
• Cross-reference classes in separate libraries.
• Supports Qt signals and slots.
• Written in perl and easily extensible.

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

• DOC++ crashed on many of our valid headers. We sent bug reports but got no reply.
• Cross-referencing to external libraries was important.
• We needed support for Qt's signals and slots.
• Both packages generated documentation with too much extraneous fluff.

Email Contact and mailing list

Please report all bug reports etc to kdoc@kde.org. Also, a mailing list for general discussion has been set up. The list address is kdoc-list@kde.org. To subscribe to the list, send an email to kdoc-list-request@kde.org with

subscribe

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:

• Normal text. Paragraphs must be separated by atleast one blank line.
• text of the form

  ---

  <pre>
  .....code fragments....
  </pre>
  

  ---

• Various tags of the form:

  @tagname [tag parameters]

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

• Classes

  @short [one sentence of text]

  A short description of the class

  @author [one sentence of text]

  Class author

  @version [once sentence of text]

  Class version (I normally set this to the RCS/CVS tag $Id: kdoc.html,v 1.6 1999/07/07 14:55:28 ssk Exp ssk $)

  @see [one or more references to classes or methods]

  References to other related documentation.

• Methods

  @see

  as above

  @return [one sentence]

  A sentence describing the return value

  @exception [exceptions]

  List the exceptions that could be thrown by this method.

  @param [param name identifier] [param description]

  Describe a parameter. The param description can span multiple lines and will be terminated by a blank line, the end of the comment, or another param entry. For this reason, param entries should normally be the last part of the doc comment.

• Constants, Enums, Properties

  @see

  as above

• ALSO @ref

  As a departure from the javadoc format, the metatag "@ref" has the same format as @see, but can appear anywhere in the documentation (all other tags must appear on a line by themselves).

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:

• The KDE core and ui library headers now contain lots of documentation.
• The definitive reference for javadoc comments at Sun.

Generating the documentation

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

• A set of HTML files (two index files and one for each class) and/or
• A set of man pages (one index page and one for each class) and
• A LaTeX file (containing all docs for the classes) and
• A file with a .kdoc extension, which can be used to reference classes and members of this library from other libraries.

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

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.