doc/mxmldoc.html - nest-hello/mxml - Git at Google

 <html>
 <body>

 <h1 align='right'><a name='MXMLDOC'><img src="4.gif" align="right"
 hspace="10" width="100" height="100" alt="4"></a>Using the mxmldoc
 Utility</h1>

 <p>This chapter describes how to use <tt>mxmldoc(1)</tt> program to
 automatically generate documentation from C and C++ source
 files.</p>


 <h2>The Basics</h2>

 <p>Originally developed to generate the Mini-XML and CUPS API
 documentation, <tt>mxmldoc</tt> 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, <tt>mxmldoc</tt>
 uses in-line comments rather than comment headers, allowing for more
 "natural" code documentation.</p>

 <p>By default, <tt>mxmldoc</tt> 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 <var>filename.html</var>:</p>

 <pre>
     <kbd>mxmldoc *.h *.c &gt;filename.html ENTER</kbd>
 </pre>

 <p>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 <var>filename.xml</var> in
 addition to the HTML file:</p>

 <pre>
     <kbd>mxmldoc filename.xml *.h *.c &gt;filename.html ENTER</kbd>
 </pre>

 <p>The <tt>--no-output</tt> option disables the normal HTML
 output:</p>

 <pre>
     <kbd>mxmldoc --no-output filename.xml *.h *.c ENTER</kbd>
 </pre>

 <p>You can then run <tt>mxmldoc</tt> again with the XML file alone
 to generate the HTML documentation:</p>

 <pre>
     <kbd>mxmldoc filename.xml &gt;filename.html ENTER</kbd>
 </pre>

 <h3>Creating Man Pages</h3>

 <p>The <tt>--man filename</tt> option tells <tt>mxmldoc</tt> to
 create a man page instead of HTML documentation, for example:</p>

 <pre>
     <kbd>mxmldoc --man filename filename.xml \
         &gt;filename.man ENTER</kbd>

     <kbd>mxmldoc --man filename *.h *.c \
         &gt;filename.man ENTER</kbd>
 </pre>

 <h3>Creating Xcode Documentation Sets</h3>

 <p>The <tt>--docset directory.docset</tt> option tells <tt>mxmldoc</tt> to
 create an Xcode documentation set containing the HTML documentation, for
 example:</p>

 <pre>
     <kbd>mxmldoc --docset foo.docset *.h *.c foo.xml ENTER</kbd>
 </pre>

 <p>Xcode documentation sets can only be built on Mac OS X with Xcode 3.0 or
 higher installed.</p>


 <h2>Commenting Your Code</h2>

 <p>As noted previously, <tt>mxmldoc</tt> looks for in-line comments
 to describe the functions, types, and constants in your code.
 <tt>Mxmldoc</tt> 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 <A
 HREF="#ATDIRECTIVES">@private@</A> directive are treated as private
 and are not documented.</p>

 <p>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:</p>

 <pre>
     /* 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 */
     {
       ...
     }
 </pre>

 <p><tt>Mxmldoc</tt> also knows to remove extra asterisks (*) from
 the comment string, so the comment string:</p>

 <pre>
     /*
      * 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.
      */
 </pre>

 <p>will be shown as:</p>

 <pre>
     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.
 </pre>

 <p><a name="ATDIRECTIVES">Comments</a> can also include the
 following special <tt>@name ...@</tt> directive strings:</p>

 <ul>

 	<li><tt>@deprecated@</tt> - flags the item as deprecated to
 	discourage its use</li>

 	<li><tt>@private@</tt> - flags the item as private so it
 	will not be included in the documentation</li>

 	<li><tt>@since ...@</tt> - flags the item as new since a
 	particular release. The text following the <tt>@since</tt>
 	up to the closing <tt>@</tt> is highlighted in the generated
 	documentation, e.g. <tt>@since Mini-XML 2.7@</tt>.</li>

 </ul>


 <!-- NEED 10 -->
 <h2>Titles, Sections, and Introductions</h2>

 <p><tt>Mxmldoc</tt> also provides options to set the title, section,
 and introduction text for the generated documentation. The
 <tt>--title text</tt> option specifies the title for the
 documentation. The title string is usually put in quotes:</p>

 <pre>
     <kbd>mxmldoc filename.xml \
         --title "My Famous Documentation" \
         &gt;filename.html ENTER</kbd>
 </pre>

 <p>The <tt>--section name</tt> option specifies the section for
 the documentation. For HTML documentation, the name is placed in
 a HTML comment such as:</p>

 <pre>
     &lt;!-- SECTION: name -->
 </pre>

 <p>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 <tt>.TH</tt> directive in the man page:</p>

 <pre>
     .TH mylibrary 3acme "My Title" ...
 </pre>

 <p>The default section name for man page output is "3". There is no
 default section name for HTML output.</p>

 <p>Finally, the <tt>--intro filename</tt> 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 <tt>DOCTYPE</tt>, <tt>html</tt>, and
 <tt>body</tt> elements. For man page documentation, the file must
 consist of valid <tt>nroff(1)</tt> text.</p>

 </body>
 </html>
	<html>
	<body>

	<h1 align='right'><a name='MXMLDOC'><img src="4.gif" align="right"
	hspace="10" width="100" height="100" alt="4"></a>Using the mxmldoc
	Utility</h1>

	<p>This chapter describes how to use <tt>mxmldoc(1)</tt> program to
	automatically generate documentation from C and C++ source
	files.</p>


	<h2>The Basics</h2>

	<p>Originally developed to generate the Mini-XML and CUPS API
	documentation, <tt>mxmldoc</tt> 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, <tt>mxmldoc</tt>
	uses in-line comments rather than comment headers, allowing for more
	"natural" code documentation.</p>

	<p>By default, <tt>mxmldoc</tt> 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 <var>filename.html</var>:</p>

	<pre>
	<kbd>mxmldoc .h .c >filename.html ENTER</kbd>
	</pre>

	<p>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 <var>filename.xml</var> in
	addition to the HTML file:</p>

	<pre>
	<kbd>mxmldoc filename.xml .h .c >filename.html ENTER</kbd>
	</pre>

	<p>The <tt>--no-output</tt> option disables the normal HTML
	output:</p>

	<pre>
	<kbd>mxmldoc --no-output filename.xml .h .c ENTER</kbd>
	</pre>

	<p>You can then run <tt>mxmldoc</tt> again with the XML file alone
	to generate the HTML documentation:</p>

	<pre>
	<kbd>mxmldoc filename.xml >filename.html ENTER</kbd>
	</pre>

	<h3>Creating Man Pages</h3>

	<p>The <tt>--man filename</tt> option tells <tt>mxmldoc</tt> to
	create a man page instead of HTML documentation, for example:</p>

	<pre>
	<kbd>mxmldoc --man filename filename.xml \
	>filename.man ENTER</kbd>

	<kbd>mxmldoc --man filename .h .c \
	>filename.man ENTER</kbd>
	</pre>

	<h3>Creating Xcode Documentation Sets</h3>

	<p>The <tt>--docset directory.docset</tt> option tells <tt>mxmldoc</tt> to
	create an Xcode documentation set containing the HTML documentation, for
	example:</p>

	<pre>
	<kbd>mxmldoc --docset foo.docset .h .c foo.xml ENTER</kbd>
	</pre>

	<p>Xcode documentation sets can only be built on Mac OS X with Xcode 3.0 or
	higher installed.</p>


	<h2>Commenting Your Code</h2>

	<p>As noted previously, <tt>mxmldoc</tt> looks for in-line comments
	to describe the functions, types, and constants in your code.
	<tt>Mxmldoc</tt> 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 <A
	HREF="#ATDIRECTIVES">@private@</A> directive are treated as private
	and are not documented.</p>

	<p>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:</p>

	<pre>
	/* 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 */
	{
	...
	}
	</pre>

	<p><tt>Mxmldoc</tt> also knows to remove extra asterisks (*) from
	the comment string, so the comment string:</p>

	<pre>
	/*
	* 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.
	*/
	</pre>

	<p>will be shown as:</p>

	<pre>
	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.
	</pre>

	<p><a name="ATDIRECTIVES">Comments</a> can also include the
	following special <tt>@name ...@</tt> directive strings:</p>

	<ul>

	<li><tt>@deprecated@</tt> - flags the item as deprecated to
	discourage its use</li>

	<li><tt>@private@</tt> - flags the item as private so it
	will not be included in the documentation</li>

	<li><tt>@since ...@</tt> - flags the item as new since a
	particular release. The text following the <tt>@since</tt>
	up to the closing <tt>@</tt> is highlighted in the generated
	documentation, e.g. <tt>@since Mini-XML 2.7@</tt>.</li>

	</ul>


	<!-- NEED 10 -->
	<h2>Titles, Sections, and Introductions</h2>

	<p><tt>Mxmldoc</tt> also provides options to set the title, section,
	and introduction text for the generated documentation. The
	<tt>--title text</tt> option specifies the title for the
	documentation. The title string is usually put in quotes:</p>

	<pre>
	<kbd>mxmldoc filename.xml \
	--title "My Famous Documentation" \
	>filename.html ENTER</kbd>
	</pre>

	<p>The <tt>--section name</tt> option specifies the section for
	the documentation. For HTML documentation, the name is placed in
	a HTML comment such as:</p>

	<pre>
	<!-- SECTION: name -->
	</pre>

	<p>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 <tt>.TH</tt> directive in the man page:</p>

	<pre>
	.TH mylibrary 3acme "My Title" ...
	</pre>

	<p>The default section name for man page output is "3". There is no
	default section name for HTML output.</p>

	<p>Finally, the <tt>--intro filename</tt> 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 <tt>DOCTYPE</tt>, <tt>html</tt>, and
	<tt>body</tt> elements. For man page documentation, the file must
	consist of valid <tt>nroff(1)</tt> text.</p>

	</body>
	</html>