homeblogprojectstextabout

kdoc

kdoc

introduction

Similar to javadoc, this is a documentation generator for C++ and IDL, capable of generating docs in a variety of formats. This tool is currently used to generate the KDE API reference.

The codebase is mostly orphaned now as I am working on a replacement, but lives on as the kalyptus project. They are using kdoc to auto-generate source code to interface Qt and KDE with other languages, particularly C, java and ObjectiveC.

KDOC is implemented in perl, which makes it relatively easy to add transformations to the abstract syntax tree created by parsing the source interface files. The parser itself is limited however, and I've somewhat lost the taste for largish apps in perl, but the fact that kalyptus proved that it could be done practically is a source of satisfaction to me.

download

Available as source archive, or RPM via rpmfind.

install

KDOC requires perl 5.6 and a unix-like operating system. Running on Windows system is possible to some extent but is not tested.

From source (tarball)

Follow the instructions in the README file in the package root.

tool docs

kdoc
Main generator script.
qt2kdoc
Generates doc cross-index file for Qt library.
makekdedoc
Makefile-like batch generator.

doc comment reference

basic syntax

See the javadoc reference for basic notes.

Doc comments are normal C-style comments that start with "/**" and directly precede the declaration which they document. They contain paragraphs of text and optional doc metadata for the declaration, usually with the form @tag. Paragraphs must be separated by atleast one blank line.

inline tags

These are embedded within paragraph text.

@ref identifier
Link to identifier, if possible. identifier can be relative or absolute.
@p identifier
highlight identifier.

block tags

These must occur at the start of a para and are para-separated themselves.

@short para
Short description of member, used in indexes etc.
@see ident [ident...]
Links to related documentation.
@image url
display image inline. not available in all output formats.
@li para
An unordered list element. Consecutive list elements will be folded into the same list. Nested lists are not yet possible.
@param paramname para
A parameter of a method.
@returns para
Explanation of the method return value.
@[throws|exception|raises] exceptionlist
A list of exceptions that a method can throw.

flags

@internal
Implementation internal member, not part of the public API.
@deprecated
Should not use and will be removed in later releases.
@abstract
Cannot be directly instantiated.
@reimplemented
Overrides superclass member of same name, generally a virtual function.
@version versiontag
@id idtag
@since versiontag
@author para

example

bugs

If you experience a problem that is not in the known bugs list, please report it on the KDE bug tracker. General queries can be sent to kdoc at kde.org.

Note that fixing this application is a very low priority for me and I don't often find the time. Patches are appreciated; I'd be much obliged if they came in ready to apply and don't break other parts of the code.