IntroductionIntroduction
Using the mxmldoc UtilityThis chapter describes how to use mxmldoc(1) program to + automatically generate documentation from C and C++ source files.
Originally developed to generate the Mini-XML and CUPS API - documentation, the mxmldoc(1) program converts C and C++ - source files into an intermediate XML format and uses in-line comments - rather than comment headers to annotate functions, types, and - constants.
- + documentation, mxmldoc 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, mxmldoc uses in-line + comments rather than comment headers, allowing for more "natural" code + documentation. +By default, mxmldoc 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 filename.html:
++ mxmldoc *.h *.c >filename.html ENTER ++
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 filename.xml in addition to the + HTML file:
++ mxmldoc filename.xml *.h *.c >filename.html ENTER ++
The --no-output option disables the normal HTML output:
++ mxmldoc --no-output filename.xml *.h *.c ENTER ++
You can then run mxmldoc again with the XML file alone to + generate the HTML documentation:
++ mxmldoc filename.xml >filename.html ENTER ++
The --man filename option tells mxmldoc to create a + man page instead of HTML documentation, for example:
++ mxmldoc --man filename filename.xml \ + >filename.man ENTER + + mxmldoc --man filename *.h *.c \ + >filename.man ENTER + + mxmldoc --man filename filename.xml *.h *.c \ + >filename.man ENTER +
mxmldoc 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.
-In general, any C or C++ source code is handled by mxmldoc, - 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".
+As noted previously, mxmldoc looks for in-line comments to + describe the functions, types, and constants in your code. Mxmldoc + 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 @private@ directive are + treated as private and are undocumented.
+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:
+
+ /* 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 */
+ {
+ ...
+ }
+
+Mxmldoc also knows to remove extra asterisks (*) from the + comment string, so the comment string:
++ /* + * 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. + */ ++
will be shown as:
++ 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. ++
Comments can also include the following + special @name ...@ directive strings:
+Mxmldoc also provides options to set the title, section, and + introduction text for the generated documentation. The --title text + option specifies the title for the documentation. The title string is + usually put in quotes:
++ mxmldoc filename.xml \ + --title "My Famous Documentation" \ + >filename.html ENTER ++
The --section name option specifies the section for the + documentation. For HTML documentation, the name is placed in a HTML + comment such as:
++ <!-- SECTION: name --> ++
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 .TH directive in the man page:
++ .TH mylibrary 3acme "My Title" ... ++
The default section name for man page output is "3". There is no + default section name for HTML output.
+Finally, the --intro filename 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 DOCTYPE, html, and body + elements. For man page documentation, the file must consist of valid +nroff(1) text.
Mini-XML LicenseData types...
+An XML element attribute value.
struct mxml_attr_s
{
@@ -3623,7 +3745,7 @@ width="80%">
mxml_attr_t
Description
-
Data types...
+An XML element attribute value.
typedef struct mxml_attr_s mxml_attr_t;
@@ -3777,5 +3899,196 @@ mxml_node_t *, int);