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
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:
<pre> .....code fragments.... </pre>
@tagname [tag parameters]
The valid tags for each type of source code entity are:
@short [one sentence of text]
@author [one sentence of text]
@version [once sentence of text]
@see [one or more references to classes or methods]
@see
@return [one sentence]
@param [param name identifier] [param description]
@see
@ref
@ref
"
has the same format as @see
, but can appear anywhere in
the documentation (all other tags must appear on a line by themselves).
See the file example.h. This is the same example I have up on the KDE Developers' Centre.
Other sources of examples:
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.
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.