This chapter describes how to use the mxmldoc(1) utility that comes with Mini-XML to automatically generate documentation for your programs.
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.
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.
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.
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 */
Each type must have a comment block immediately before the typedef, as follows:
/*
* This type is for foobar options.
*/
typedef int this_type_t;
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);
}
};
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 */
};
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.
<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"/>
|
<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"/>
|
<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>
|
</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>
|