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> |
<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> |
<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 --> |
<!-- NEW PAGE --> |
||||||
<center><table border='1' width='80%' bgcolor='#cccccc' cellpadding='5' cellspacing='0'> |
<h2 class='title'><a name='mxmldoc.1'>mxmldoc(1)</a></h2> |
||||||
<caption align='bottom'><i>Listing 4-1, XML Schema File "mxmldoc.xsd" (con't)</i></caption> |
<h3 _hd_omit_toc>Name</h3> |
||||||
<tr><td> |
mxmldoc - mini-xml documentation generator |
||||||
<pre> |
<h3 _hd_omit_toc>Synopsis</h3> |
||||||
<xsd:element ref="struct"/> |
<b>mxmldoc |
||||||
<xsd:element ref="typedef"/> |
</b>[ --intro |
||||||
<xsd:element ref="union"/> |
<i>introfile.html |
||||||
<xsd:element ref="variable"/> |
</i>] [ --section |
||||||
</xsd:choice> |
<i>section |
||||||
</xsd:sequence> |
</i>] [ --title |
||||||
<xsd:attribute name="name" type="identifier" use="required"/> |
<i>title |
||||||
</xsd:complexType> |
</i>] [ |
||||||
|
<i>filename.xml |
||||||
<xsd:complexType name="returnvalueType"> |
</i>] [ |
||||||
<xsd:sequence> |
<i>source file(s) |
||||||
<xsd:element ref="type" minOccurs="1" maxOccurs="1"/> |
</i>] > |
||||||
<xsd:element ref="description" minOccurs="0" maxOccurs="1"/> |
<i>filename.html |
||||||
</xsd:sequence> |
</i><h3 _hd_omit_toc>Description</h3> |
||||||
</xsd:complexType> |
<i>mxmldoc</i> scans the specified C and C++ source files to |
||||||
|
produce an XML representation of globally accessible classes, |
||||||
<xsd:complexType name="structType"> |
constants, enumerations, functions, structures, typedefs, |
||||||
<xsd:sequence> |
unions, and variables. The XML file is updated as necessary and |
||||||
<xsd:element ref="description" minOccurs="0" maxOccurs="1"/> |
a HTML representation of the XML file is written to the standard |
||||||
<xsd:choice minOccurs="0" maxOccurs="unbounded"> |
output. If no source files are specified then the current XML |
||||||
<xsd:element ref="variable"/> |
file is converted to HTML on the standard output. |
||||||
<xsd:element ref="function"/> |
<p>In general, any C or C++ source code is handled by |
||||||
</xsd:choice> |
<i>mxmldoc</i>, however it was specifically written to handle |
||||||
</xsd:sequence> |
code with documentation that is formatted according to the CUPS |
||||||
<xsd:attribute name="name" type="identifier" use="required"/> |
Configuration Management Plan which is available at |
||||||
</xsd:complexType> |
"http://www.cups.org/documentation.php". |
||||||
|
<h3 _hd_omit_toc>Options</h3> |
||||||
<xsd:complexType name="typedefType"> |
<dl> |
||||||
<xsd:sequence> |
<dt>--intro introfile.html |
||||||
<xsd:element ref="type" minOccurs="1" maxOccurs="1"/> |
</dt> |
||||||
<xsd:element ref="description" minOccurs="0" maxOccurs="1"/> |
<dd>Inserts the specified file at the top of the output documentation. |
||||||
</xsd:sequence> |
</dd> |
||||||
<xsd:attribute name="name" type="identifier" use="required"/> |
<dt>--section section |
||||||
</xsd:complexType> |
</dt> |
||||||
|
<dd>Sets the section/keywords in the output documentation. |
||||||
<xsd:complexType name="unionType"> |
</dd> |
||||||
<xsd:sequence> |
<dt>--title title |
||||||
<xsd:element ref="description" minOccurs="0" maxOccurs="1"/> |
</dt> |
||||||
<xsd:element ref="variable" minOccurs="0" maxOccurs="unbounded"/> |
<dd>Sets the title of the output documentation. |
||||||
</xsd:sequence> |
</dd> |
||||||
<xsd:attribute name="name" type="identifier" use="required"/> |
</dl> |
||||||
</xsd:complexType> |
<h3 _hd_omit_toc>See Also</h3> |
||||||
|
mxml(3), Mini-XML Programmers Manual, http://www.easysw.com/~mike/mxml/ |
||||||
<xsd:complexType name="variableType"> |
<h3 _hd_omit_toc>Copyright</h3> |
||||||
<xsd:sequence> |
Copyright 2003-2005 by Michael Sweet. |
||||||
<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> |
|
||||||
|
|
||||||
</body> |
</body> |
||||||
</html> |
</html> |
||||||
|
|||||||
Loading…
Reference in new issue