From 7d8801c7dd1d55ace2ae125dcb01434796add5d0 Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Fri, 27 Apr 2007 01:10:20 +0000 Subject: [PATCH] Update docos. --- doc/makedocs.sh | 2 +- doc/mxml.html | 363 ++++++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 339 insertions(+), 26 deletions(-) diff --git a/doc/makedocs.sh b/doc/makedocs.sh index a0f0079..b6e1a7a 100755 --- a/doc/makedocs.sh +++ b/doc/makedocs.sh @@ -17,7 +17,7 @@ # GNU General Public License for more details. # -htmldoc --verbose --path hires:. --batch mxml.book -f mxml.pdf +htmldoc --verbose --path "hires;." --batch mxml.book -f mxml.pdf htmldoc --verbose --batch mxml.book --no-title -f mxml.html diff --git a/doc/mxml.html b/doc/mxml.html index 90a2579..eb9936e 100644 --- a/doc/mxml.html +++ b/doc/mxml.html @@ -68,9 +68,7 @@ A { text-decoration: none } Mini-XML License
@@ -174,6 +172,8 @@ A { text-decoration: none } +XML Schema +

0Introduction

@@ -229,6 +229,8 @@ libxml2 library with something substantially smaller and changes in each release of Mini-XML.
  • Appendix C, "Library Reference", contains a complete reference for Mini-XML, generated by mxmldoc.
    • +
  • Appendix D, "XML Schema", shows the XML schema + used for the XML files produced by mxmldoc.
    • @@ -1345,28 +1347,148 @@ mxmlRetain function. For example, the following SAX callback

    4Using the mxmldoc Utility

    +

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

    The Basics

    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
+

    Commenting Your Code

    -

    Creating HTML Documentation

    -

    Creating Man Pages

    -

    The XML Schema

    -

    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:

    + + + +

    Titles, Sections, and Introductions

    +

    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.

    AMini-XML License

    @@ -3461,7 +3583,7 @@ width="80%">

    mxml_attr_s

    Description

    -

    Data types...

    +

    An XML element attribute value.

    Definition

    struct mxml_attr_s
    { @@ -3623,7 +3745,7 @@ width="80%">

    mxml_attr_t

    Description

    -

    Data types...

    +

    An XML element attribute value.

    Definition

    typedef struct mxml_attr_s mxml_attr_t;

    @@ -3777,5 +3899,196 @@ mxml_node_t *, int);

    realReal number textText fragment - +
    +

    DXML Schema

    +

    This appendix provides the XML schema that is used for the XML files + produced by mxmldoc. This schema is available on-line at:

    +
    +    http://www.easysw.com/~mike/mxmldoc.xsd
+
    +

    mxmldoc.xsd

    +
    
+<?xml version="1.0"?>
+<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+  <xsd:annotation>
+    <xsd:documentation xml:lang="en">
+      Mini-XML 2.3 documentation schema for mxmldoc output.
+      Copyright 2003-2007 by Michael Sweet.
+    </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"/>
+	<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"/>
+	<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:complexType>
+
+  <xsd:complexType name="returnvalueType">
+    <xsd:sequence>
+      <xsd:element ref="type" minOccurs="1" maxOccurs="1"/>
+      <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
+    </xsd:sequence>
+  </xsd:complexType>
+
+  <xsd:complexType name="structType">
+    <xsd:sequence>
+      <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
+      <xsd:choice minOccurs="0" maxOccurs="unbounded">
+	<xsd:element ref="variable"/>
+	<xsd:element ref="function"/>
+      </xsd:choice>
+    </xsd:sequence>
+    <xsd:attribute name="name" type="identifier" use="required"/>
+  </xsd:complexType>
+
+  <xsd:complexType name="typedefType">
+    <xsd:sequence>
+      <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>
+
+  <xsd:complexType name="unionType">
+    <xsd:sequence>
+      <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
+      <xsd:element ref="variable" minOccurs="0" maxOccurs="unbounded"/>
+    </xsd:sequence>
+    <xsd:attribute name="name" type="identifier" use="required"/>
+  </xsd:complexType>
+
+  <xsd:complexType name="variableType">
+    <xsd:sequence>
+      <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>
+  </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>
+
    +