📄 mxmldoc.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 mxmldocUtility</h1><p>This chapter describes how to use <tt>mxmldoc(1)</tt> program toautomatically generate documentation from C and C++ sourcefiles.</p><h2>The Basics</h2><p>Originally developed to generate the Mini-XML and CUPS APIdocumentation, <tt>mxmldoc</tt> is now a general-purpose utilitywhich scans C and C++ source files to produce HTML and man pagedocumentation along with an XML file representing the functions,types, and definitions in those source files. Unlike populardocumentation 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. Forexample, the following command will scan all of the C source andheader files in the current directory and produce a HTMLdocumentation 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 ofthe information from the source files. For example, the followingcommand creates an XML file called <var>filename.xml</var> inaddition 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 HTMLoutput:</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 aloneto generate the HTML documentation:</p><pre> <kbd>mxmldoc filename.xml >filename.html ENTER</kbd></pre><p>The <tt>--man filename</tt> option tells <tt>mxmldoc</tt> tocreate 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> <kbd>mxmldoc --man filename filename.xml *.h *.c \ >filename.man ENTER</kbd></pre><h2>Commenting Your Code</h2><p>As noted previously, <tt>mxmldoc</tt> looks for in-line commentsto describe the functions, types, and constants in your code.<tt>Mxmldoc</tt> will document all public names it finds in yoursource files - any names starting with the underscore character (_) or names that are documented with the <AHREF="#ATDIRECTIVES">@private@</A> directive are treated as privateand are undocumented.</p><p>Comments appearing directly before a function or type definitionare used to document that function or type. Comments appearing afterargument, definition, return type, or variable declarations are usedto document that argument, definition, return type, or variable. Forexample, the following code excerpt defines a key/value structureand 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 (*) fromthe 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 thefollowing 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 CUPS 1.3@</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 thedocumentation. 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 forthe documentation. For HTML documentation, the name is placed ina 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 isused 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 nodefault section name for HTML output.</p><p>Finally, the <tt>--intro filename</tt> option specifies a file toembed after the title and section but before the generateddocumentation. For HTML documentation, the file must consist ofvalid HTML without the usual <tt>DOCTYPE</tt>, <tt>html</tt>, and<tt>body</tt> elements. For man page documentation, the file mustconsist of valid <tt>nroff(1)</tt> text.</p></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -