219 lines
6.5 KiB
HTML
219 lines
6.5 KiB
HTML
|
<html>
|
||
|
|
<body>
|
||
|
|
|
||
|
|
<h1 align='right'><a name='MXMLDOC'>Chapter 4 - Using the mxmldoc
|
||
|
|
Utility</a></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 EPUB Books</h3>
|
||
|
|
|
||
|
|
<p>The <tt>--epub filename.epub</tt> option tells <tt>mxmldoc</tt> to
|
||
|
|
create an EPUB book containing the HTML documentation, for example:</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
<kbd>mxmldoc --epub foo.epub *.h *.c foo.xml 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 macOS 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>@exclude format[,...,format]@</tt> - excludes the item from the
|
||
|
|
documentation in the specified formats: "all" for all formats, "docset"
|
||
|
|
for Xcode documentation sets, "epub" for EPUB books, "html" for HTML
|
||
|
|
output, and "man" for man page output</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>
|