Udoc syntax

Udoc processes documentation blocks. Such a block either precedes a member function or stands on its own.

Here's an example:

/*! \class Object object.h

The Object class models any kind of object.

All other classes inherit from this class; all behaviour which is shared between all classes is defined here.

*/

A documentation block is a C-style comment whose first character is a '!' (exclamation mark). This particular block documents a class called Object, which is used using '#include <object.h>'.

udoc takes almost plain text as input. Paragraphs are separated by empty lines. Other white space doesn't matter. Words with start with '\' (such as \class in the preceding example) are udoc directives.

Another example:

/*! As Output::addClass(). If part of \a text corresponds to the name of \a c, then only that part is italicized, otherwise all of \a text is.

*/

void ManPage::addClass( const String & text, Class * c )
{
    ….

This block documents the function that immediately follows it. '\a word' is udoc's most-used directive. It means that word is an argument name. udoc complains if an argument name is documented but not used, or used but not documented.

Note that in this example, udoc will see that the word Output::addClass() looks like a function name, and will either add a link to the documentation for Output::addClass() or emit an error message saying it can't find a target for the the name.

Almost all udoc blocks look like one of the two above examples. Congratulations, you've learnt to use udoc! The other directives are as follows, in case you like to read reference manuals:

'\overload' means that a function is an secondary version of another function. For example, QWidget::resize() exists in two versions, one which takes a QSize argument and one which takes two integers. There wouldn't be much point to documenting both in the same way, so udoc lets you designate one as the real function, and the others as overloaded alternatives.

'\nodoc' means that a source file contains no documentation, on purpose. Normally udoc assumes that all the files on its command line should contain some documentation, and gives you an error message if that isn't the case.

'\fn function signature' means that the documentation block documents that function signature. This is useful for inline functions.

Every other word starting with '\' results in an error message. There's no escape mechanism. I considered it more important to catch typos (e.g. '\s' for '\a') than to support general use of backslashes. At Oryx, we rewrite to avoid a leading backslash, e.g. we mention the '\recent' IMAP flag rather than the \recent flag.

Other members of udoc's family tree have many more directives. This one is simple on purpose: As a tool for our development process, udoc seems to work best when it concentrates on the vital minimum. If the documentation tool is more complex, we fallible humans seem to shirk more often.

Relevant links

About this page

Last modified: 2010-11-19
Location: aox.org/udoc/syntax