4Using the mxmldoc Utility

This chapter describes how to use mxmldoc(1) program to automatically generate documentation from C and C++ source files.

The Basics

Originally developed to generate the Mini-XML and CUPS API documentation, mxmldoc is now a general-purpose utility which scans C and C++ source files to produce HTML and man page documentation along with an XML file representing the functions, types, and definitions in those source files. Unlike popular documentation generators like Doxygen or Javadoc, mxmldoc uses in-line comments rather than comment headers, allowing for more "natural" code documentation.

By default, mxmldoc produces HTML documentation. For example, the following command will scan all of the C source and header files in the current directory and produce a HTML documentation file called filename.html:

    mxmldoc *.h *.c >filename.html ENTER

You can also specify an XML file to create which contains all of the information from the source files. For example, the following command creates an XML file called filename.xml in addition to the HTML file:

    mxmldoc filename.xml *.h *.c >filename.html ENTER

The --no-output option disables the normal HTML output:

    mxmldoc --no-output filename.xml *.h *.c ENTER

You can then run mxmldoc again with the XML file alone to generate the HTML documentation:

    mxmldoc filename.xml >filename.html ENTER

Creating Man Pages

The --man filename option tells mxmldoc to create a man page instead of HTML documentation, for example:

    mxmldoc --man filename filename.xml \
        >filename.man ENTER

    mxmldoc --man filename *.h *.c \
        >filename.man ENTER

Creating Xcode Documentation Sets

The --docset directory.docset option tells mxmldoc to create an Xcode documentation set containing the HTML documentation, for example:

    mxmldoc --docset foo.docset *.h *.c foo.xml ENTER

Xcode documentation sets can only be built on Mac OS X with Xcode 3.0 or higher installed.

Commenting Your Code

As noted previously, mxmldoc looks for in-line comments to describe the functions, types, and constants in your code. Mxmldoc will document all public names it finds in your source files - any names starting with the underscore character (_) or names that are documented with the @private@ directive are treated as private and are not documented.

Comments appearing directly before a function or type definition are used to document that function or type. Comments appearing after argument, definition, return type, or variable declarations are used to document that argument, definition, return type, or variable. For example, the following code excerpt defines a key/value structure and a function that creates a new instance of that structure:

    /* A key/value pair. This is used with the
       dictionary structure. */

    struct keyval
    {
      char *key; /* Key string */
      char *val; /* Value string */
    };

    /* Create a new key/value pair. */

    struct keyval * /* New key/value pair */
    new_keyval(
        const char *key, /* Key string */
	const char *val) /* Value string */
    {
      ...
    }

Mxmldoc also knows to remove extra asterisks (*) from the comment string, so the comment string:

    /*
     * Compute the value of PI.
     *
     * The function connects to an Internet server
     * that streams audio of mathematical monks
     * chanting the first 100 digits of PI.
     */

will be shown as:

    Compute the value of PI.

    The function connects to an Internet server
    that streams audio of mathematical monks
    chanting the first 100 digits of PI.

Comments can also include the following special @name ...@ directive strings:

Titles, Sections, and Introductions

Mxmldoc also provides options to set the title, section, and introduction text for the generated documentation. The --title text option specifies the title for the documentation. The title string is usually put in quotes:

    mxmldoc filename.xml \
        --title "My Famous Documentation" \
        >filename.html ENTER

The --section name option specifies the section for the documentation. For HTML documentation, the name is placed in a HTML comment such as:

    <!-- SECTION: name -->

For man pages, the section name is usually just a number ("3"), or a number followed by a vendor name ("3acme"). The section name is used in the .TH directive in the man page:

    .TH mylibrary 3acme "My Title" ...

The default section name for man page output is "3". There is no default section name for HTML output.

Finally, the --intro filename option specifies a file to embed after the title and section but before the generated documentation. For HTML documentation, the file must consist of valid HTML without the usual DOCTYPE, html, and body elements. For man page documentation, the file must consist of valid nroff(1) text.