# Using 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:

- `@deprecated@` - flags the item as deprecated to discourage its use
- `@private@` - flags the item as private so it will not be included in the documentation
- `@since ...@` - flags the item as new since a particular release. The text following the `@since` up to the closing `@` is highlighted in the generated documentation, e.g. `@since Mini-XML 2.7@`.

## 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.