# 4 - Using the mxmldoc Utility

This chapter describes how to use the `mxmldoc(1)` utility that comes with Mini-XML to automatically generate documentation for your programs.

## The Basics

The `mxmldoc` utility scans C and C++ source and header files and produces an XML file describing the library interface and an XHTML file providing a human-readable reference to the code. Each source and header file must conform to some simple code commenting conventions so that `mxmldoc` can extract the necessary descriptive text.

The `mxmldoc` command requires the name of an XML file to store the code information; this file is created and updated as necessary. The XML file is optionally followed by a list of source files to scan. After scanning any source files on the command-line, `mxmldoc` writes XHTML documentation to the standard output, which can be redirected to the file using the `>filename` syntax:

        mxmldoc myfile.xml >myfile.html ENTER
        mxmldoc myfile.xml file1.c file2.cxx file3.h >myfile.html ENTER

If no source files are provided on the command-line, the current contents of the XML file are converted to XHTML.

## Code Documentation Conventions

As noted previously, source code must be commented properly for `mxmldoc` to generate correct documentation for the code. Single line comments can use the C++ `//` comment sequence, however all multi-line comments must use the C `/* ... */` comment sequence.

### Functions and Methods

All implementations of functions and methods must begin with a comment header describing what the function does, the possible input limits (if any), and the possible output values (if any), and any special information needed, as follows:

        /*
         * 'do_this()' - Compute y = this(x).
         *
         * Notes: none.
         */

        float            /* O - Inverse power value, 0.0 <= y <= 1.1 */
        do_this(float x) /* I - Power value (0.0 <= x <= 1.1) */
        {
          ...
          return (y);
        }

Return/output values are indicated using an "O" prefix, input values are indicated using the "I" prefix, and values that are both input and output use the "IO" prefix for the corresponding in-line comment.

### Variables and Class/Structure/Union Members

Each variable or member must be declared on a separate line and must be immediately followed by a comment describing the variable or member, as follows:

        int this_variable;   /* The current state of this */
        int that_variable;   /* The current state of that */

### Types

Each type must have a comment block immediately before the typedef, as follows:

        /*
         * This type is for foobar options.
         */
        typedef int this_type_t;

### Classes, Structures, and Unions

Each class, structure, and union must have a comment block immediately before the definition, and each member must be documented in accordance with the function and variable documentation requirements, as follows:

        /*
         * This structure is for foobar options.
         */
        struct this_struct_s
        {
          int this_member;   /* Current state for this */
          int that_member;   /* Current state for that */
        };

        /*
         * This class is for barfoo options.
         */
        class this_class_c
        {
          int this_member;   /* Current state for this */
          int that_member;   /* Current state for that */

          /*
           * 'get_this()' - Get the current state for this.
           */
          int                /* O - Current state for this */
          get_this()
          {
            return (this_member);
          }
        };

### Enumerations

Each enumeration must have a comment block immediately before the definition describing what the enumeration is for, and each enumeration value must have a comment immediately after the value, as follows:

       /*
        * Enumeration of media trays.
        */
        enum this_enum_e
        {
          THIS_TRAY,   /* This tray */
          THAT_TRAY    /* That tray */
        };

## XML Schema

Listing 4-1 shows the XML schema file mxmldoc.xsd which is included with Mini-XML. This schema file can be used to convert the XML files produced by `mxmldoc` into other formats.

Listing 4-1, XML Schema File "mxmldoc.xsd"
    <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          Mini-XML 2.2 documentation schema for mxmldoc output.
          Copyright 2003-2005 by Michael Sweet.

          This program is free software; you can redistribute it and/or
          modify it under the terms of the GNU Library General Public
          License as published by the Free Software Foundation; either
          version 2, or (at your option) any later version.

          This program is distributed in the hope that it will be useful,
          but WITHOUT ANY WARRANTY; without even the implied warranty of
          MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
          GNU General Public License for more details.
        </xsd:documentation>
      </xsd:annotation>

      <!-- basic element definitions -->
      <xsd:element name="argument" type="argumentType"/>
      <xsd:element name="class" type="classType"/>
      <xsd:element name="constant" type="constantType"/>
      <xsd:element name="description" type="xsd:string"/>
      <xsd:element name="enumeration" type="enumerationType"/>
      <xsd:element name="function" type="functionType"/>
      <xsd:element name="mxmldoc" type="mxmldocType"/>
      <xsd:element name="namespace" type="namespaceType"/>
      <xsd:element name="returnvalue" type="returnvalueType"/>
      <xsd:element name="seealso" type="identifierList"/>
      <xsd:element name="struct" type="structType"/>
      <xsd:element name="typedef" type="typedefType"/>
      <xsd:element name="type" type="xsd:string"/>
      <xsd:element name="union" type="unionType"/>
      <xsd:element name="variable" type="variableType"/>

      <!-- descriptions of complex elements -->
      <xsd:complexType name="argumentType">
        <xsd:sequence>
          <xsd:element ref="type" minOccurs="1" maxOccurs="1"/>
          <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
        </xsd:sequence>
        <xsd:attribute name="default" type="xsd:string" use="optional"/>
        <xsd:attribute name="name" type="identifier" use="required"/>
        <xsd:attribute name="direction" type="direction" use="optional" default="I"/>
      </xsd:complexType>

      <xsd:complexType name="classType">
        <xsd:sequence>
          <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
          <xsd:choice minOccurs="0" maxOccurs="unbounded">
    	<xsd:element ref="class"/>

Listing 4-1, XML Schema File "mxmldoc.xsd" (con't)
    	<xsd:element ref="enumeration"/>
    	<xsd:element ref="function"/>
    	<xsd:element ref="struct"/>
    	<xsd:element ref="typedef"/>
    	<xsd:element ref="union"/>
    	<xsd:element ref="variable"/>
          </xsd:choice>
        </xsd:sequence>
        <xsd:attribute name="name" type="identifier" use="required"/>
        <xsd:attribute name="parent" type="xsd:string" use="optional"/>
      </xsd:complexType>

      <xsd:complexType name="constantType">
        <xsd:sequence>
          <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
        </xsd:sequence>
        <xsd:attribute name="name" type="identifier" use="required"/>
      </xsd:complexType>

      <xsd:complexType name="enumerationType">
        <xsd:sequence>
          <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
          <xsd:element ref="constant" minOccurs="1" maxOccurs="unbounded"/>
        </xsd:sequence>
        <xsd:attribute name="name" type="identifier" use="required"/>
      </xsd:complexType>

      <xsd:complexType name="functionType">
        <xsd:sequence>
          <xsd:element ref="returnvalue" minOccurs="0" maxOccurs="1"/>
          <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
          <xsd:element ref="argument" minOccurs="1" maxOccurs="unbounded"/>
          <xsd:element ref="seealso" minOccurs="0" maxOccurs="1"/>
        </xsd:sequence>
        <xsd:attribute name="name" type="identifier" use="required"/>
        <xsd:attribute name="scope" type="scope" use="optional"/>
      </xsd:complexType>

      <xsd:complexType name="mxmldocType">
        <xsd:choice minOccurs="0" maxOccurs="unbounded">
          <xsd:element ref="class"/>
          <xsd:element ref="enumeration"/>
          <xsd:element ref="function"/>
          <xsd:element ref="namespace"/>
          <xsd:element ref="struct"/>
          <xsd:element ref="typedef"/>
          <xsd:element ref="union"/>
          <xsd:element ref="variable"/>
        </xsd:choice>
      </xsd:complexType>

      <xsd:complexType name="namespaceType">
        <xsd:sequence>
          <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
          <xsd:choice minOccurs="0" maxOccurs="unbounded">
    	<xsd:element ref="class"/>
    	<xsd:element ref="enumeration"/>
    	<xsd:element ref="function"/>

Listing 4-1, XML Schema File "mxmldoc.xsd" (con't)
    	<xsd:element ref="struct"/>
    	<xsd:element ref="typedef"/>
    	<xsd:element ref="union"/>
    	<xsd:element ref="variable"/>
          </xsd:choice>
        </xsd:sequence>
        <xsd:attribute name="name" type="identifier" use="required"/>
      </xsd:complexType>

      <xsd:complexType name="returnvalueType">
        <xsd:sequence>
          <xsd:element ref="type" minOccurs="1" maxOccurs="1"/>
          <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
        </xsd:sequence>
      </xsd:complexType>

      <xsd:complexType name="structType">
        <xsd:sequence>
          <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
          <xsd:choice minOccurs="0" maxOccurs="unbounded">
    	<xsd:element ref="variable"/>
    	<xsd:element ref="function"/>
          </xsd:choice>
        </xsd:sequence>
        <xsd:attribute name="name" type="identifier" use="required"/>
      </xsd:complexType>

      <xsd:complexType name="typedefType">
        <xsd:sequence>
          <xsd:element ref="type" minOccurs="1" maxOccurs="1"/>
          <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
        </xsd:sequence>
        <xsd:attribute name="name" type="identifier" use="required"/>
      </xsd:complexType>

      <xsd:complexType name="unionType">
        <xsd:sequence>
          <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
          <xsd:element ref="variable" minOccurs="0" maxOccurs="unbounded"/>
        </xsd:sequence>
        <xsd:attribute name="name" type="identifier" use="required"/>
      </xsd:complexType>

      <xsd:complexType name="variableType">
        <xsd:sequence>
          <xsd:element ref="type" minOccurs="1" maxOccurs="1"/>
          <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
        </xsd:sequence>
        <xsd:attribute name="name" type="identifier" use="required"/>
      </xsd:complexType>

      <!-- data types -->
      <xsd:simpleType name="direction">
        <xsd:restriction base="xsd:string">
          <xsd:enumeration value="I"/>
          <xsd:enumeration value="O"/>
          <xsd:enumeration value="IO"/>
        </xsd:restriction>

Listing 4-1, XML Schema File "mxmldoc.xsd" (con't)
      </xsd:simpleType>

      <xsd:simpleType name="identifier">
        <xsd:restriction base="xsd:string">
          <xsd:pattern value="[a-zA-Z_(.]([a-zA-Z_(.,)* 0-9])*"/>
        </xsd:restriction>
      </xsd:simpleType>

      <xsd:simpleType name="identifierList">
        <xsd:list itemType="identifier"/>
      </xsd:simpleType>

      <xsd:simpleType name="scope">
        <xsd:restriction base="xsd:string">
          <xsd:enumeration value=""/>
          <xsd:enumeration value="private"/>
          <xsd:enumeration value="protected"/>
          <xsd:enumeration value="public"/>
        </xsd:restriction>
      </xsd:simpleType>
    </xsd:schema>