Michael R Sweet
19 years ago
parent
2e7bc89ddd
commit
cc5890089d
File diff suppressed because it is too large
Load Diff
@ -1,378 +1,66 @@ |
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> |
||||
<html> |
||||
<!-- SECTION: Man Pages --> |
||||
<head> |
||||
<style type='text/css'><!-- |
||||
h1, h2, h3, p { font-family: sans-serif; text-align: justify; } |
||||
tt, pre a:link, pre a:visited, tt a:link, tt a:visited { font-weight: bold; color: #7f0000; } |
||||
pre { font-weight: bold; color: #7f0000; margin-left: 2em; } |
||||
h1.title, h2.title, h3.title { border-bottom: solid 2px #000000; } |
||||
--></style> |
||||
<title>mxmldoc</title> |
||||
</head> |
||||
<body> |
||||
|
||||
<h1 align='right'><a name='MXMLDOC'>4 - Using the mxmldoc |
||||
Utility</a></h1> |
||||
|
||||
<p>This chapter describes how to use the <tt>mxmldoc(1)</tt> |
||||
utility that comes with Mini-XML to automatically generate |
||||
documentation for your programs.</p> |
||||
|
||||
<h2>The Basics</h2> |
||||
|
||||
<p>The <tt>mxmldoc</tt> 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 <tt>mxmldoc</tt> can |
||||
extract the necessary descriptive text.</p> |
||||
|
||||
<p>The <tt>mxmldoc</tt> 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, <tt>mxmldoc</tt> writes XHTML documentation to the |
||||
standard output, which can be redirected to the file using the |
||||
<kbd>>filename</kbd> syntax:</p> |
||||
|
||||
<pre> |
||||
<kbd>mxmldoc myfile.xml >myfile.html ENTER</kbd> |
||||
<kbd>mxmldoc myfile.xml file1.c file2.cxx file3.h >myfile.html ENTER</kbd> |
||||
</pre> |
||||
|
||||
<p>If no source files are provided on the command-line, the |
||||
current contents of the XML file are converted to XHTML.</p> |
||||
|
||||
<h2>Code Documentation Conventions</h2> |
||||
|
||||
<p>As noted previously, source code must be commented properly |
||||
for <tt>mxmldoc</tt> to generate correct documentation for the |
||||
code. Single line comments can use the C++ <tt>//</tt> comment |
||||
sequence, however all multi-line comments must use the C <tt>/* |
||||
... */</tt> comment sequence.</p> |
||||
|
||||
<h3>Functions and Methods</h3> |
||||
|
||||
<p>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:</p> |
||||
|
||||
<pre> |
||||
/* |
||||
* '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); |
||||
} |
||||
</pre> |
||||
|
||||
<p>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.</p> |
||||
|
||||
<h3>Variables and Class/Structure/Union Members</h3> |
||||
|
||||
<p>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:</p> |
||||
|
||||
<pre> |
||||
int this_variable; /* The current state of this */ |
||||
int that_variable; /* The current state of that */ |
||||
</pre> |
||||
|
||||
<h3>Types</h3> |
||||
|
||||
<p>Each type must have a comment block immediately before the |
||||
typedef, as follows:</p> |
||||
|
||||
<pre> |
||||
/* |
||||
* This type is for foobar options. |
||||
*/ |
||||
typedef int this_type_t; |
||||
</pre> |
||||
|
||||
<!-- NEED 5in --> |
||||
<h3>Classes, Structures, and Unions</h3> |
||||
|
||||
<p>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:</p> |
||||
|
||||
<pre> |
||||
/* |
||||
* 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); |
||||
} |
||||
}; |
||||
</pre> |
||||
|
||||
<h3>Enumerations</h3> |
||||
|
||||
<p>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:</p> |
||||
|
||||
<pre> |
||||
/* |
||||
* Enumeration of media trays. |
||||
*/ |
||||
enum this_enum_e |
||||
{ |
||||
THIS_TRAY, /* This tray */ |
||||
THAT_TRAY /* That tray */ |
||||
}; |
||||
</pre> |
||||
|
||||
<!-- NEW PAGE --> |
||||
<h2>XML Schema</h2> |
||||
|
||||
<p>Listing 4-1 shows the XML schema file <var>mxmldoc.xsd</var> |
||||
which is included with Mini-XML. This schema file can be used to |
||||
convert the XML files produced by <tt>mxmldoc</tt> into other |
||||
formats.</p> |
||||
|
||||
<center><table border='1' width='80%' bgcolor='#cccccc' cellpadding='5' cellspacing='0'> |
||||
<caption align='bottom'><i>Listing 4-1, XML Schema File "mxmldoc.xsd"</i></caption> |
||||
<tr><td> |
||||
<pre> |
||||
<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"/> |
||||
</pre> |
||||
</td></tr> |
||||
</table></center> |
||||
<!-- NEW PAGE --> |
||||
<center><table border='1' width='80%' bgcolor='#cccccc' cellpadding='5' cellspacing='0'> |
||||
<caption align='bottom'><i>Listing 4-1, XML Schema File "mxmldoc.xsd" (con't)</i></caption> |
||||
<tr><td> |
||||
<pre> |
||||
<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"/> |
||||
</pre> |
||||
</td></tr> |
||||
</table></center> |
||||
<!-- NEW PAGE --> |
||||
<center><table border='1' width='80%' bgcolor='#cccccc' cellpadding='5' cellspacing='0'> |
||||
<caption align='bottom'><i>Listing 4-1, XML Schema File "mxmldoc.xsd" (con't)</i></caption> |
||||
<tr><td> |
||||
<pre> |
||||
<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> |
||||
</pre> |
||||
</td></tr> |
||||
</table></center> |
||||
<!-- NEW PAGE --> |
||||
<center><table border='1' width='80%' bgcolor='#cccccc' cellpadding='5' cellspacing='0'> |
||||
<caption align='bottom'><i>Listing 4-1, XML Schema File "mxmldoc.xsd" (con't)</i></caption> |
||||
<tr><td> |
||||
<pre> |
||||
</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> |
||||
</pre> |
||||
</td></tr> |
||||
</table></center> |
||||
<h2 class='title'><a name='mxmldoc.1'>mxmldoc(1)</a></h2> |
||||
<h3 _hd_omit_toc>Name</h3> |
||||
mxmldoc - mini-xml documentation generator |
||||
<h3 _hd_omit_toc>Synopsis</h3> |
||||
<b>mxmldoc |
||||
</b>[ --intro |
||||
<i>introfile.html |
||||
</i>] [ --section |
||||
<i>section |
||||
</i>] [ --title |
||||
<i>title |
||||
</i>] [ |
||||
<i>filename.xml |
||||
</i>] [ |
||||
<i>source file(s) |
||||
</i>] > |
||||
<i>filename.html |
||||
</i><h3 _hd_omit_toc>Description</h3> |
||||
<i>mxmldoc</i> scans the specified C and C++ source files to |
||||
produce an XML representation of globally accessible classes, |
||||
constants, enumerations, functions, structures, typedefs, |
||||
unions, and variables. The XML file is updated as necessary and |
||||
a HTML representation of the XML file is written to the standard |
||||
output. If no source files are specified then the current XML |
||||
file is converted to HTML on the standard output. |
||||
<p>In general, any C or C++ source code is handled by |
||||
<i>mxmldoc</i>, however it was specifically written to handle |
||||
code with documentation that is formatted according to the CUPS |
||||
Configuration Management Plan which is available at |
||||
"http://www.cups.org/documentation.php". |
||||
<h3 _hd_omit_toc>Options</h3> |
||||
<dl> |
||||
<dt>--intro introfile.html |
||||
</dt> |
||||
<dd>Inserts the specified file at the top of the output documentation. |
||||
</dd> |
||||
<dt>--section section |
||||
</dt> |
||||
<dd>Sets the section/keywords in the output documentation. |
||||
</dd> |
||||
<dt>--title title |
||||
</dt> |
||||
<dd>Sets the title of the output documentation. |
||||
</dd> |
||||
</dl> |
||||
<h3 _hd_omit_toc>See Also</h3> |
||||
mxml(3), Mini-XML Programmers Manual, http://www.easysw.com/~mike/mxml/ |
||||
<h3 _hd_omit_toc>Copyright</h3> |
||||
Copyright 2003-2005 by Michael Sweet. |
||||
|
||||
</body> |
||||
</html> |
||||
|
||||
Loading…
Reference in new issue