doc/classlib-doc

   1 * Class Library Documentation
   2
   3 ** Summary
   4
   5         <em>
   6         [This documentation is in progress.  Comments to
   7         <a href="mailto:jbarn@httcb.net">jbarn@httcb.net</a>.]
   8         </em>
   9
  10         While using inline XML tags to document classes is certainly
  11         convenient, properly verbose documentation quickly overwhelms
  12         the code, making the source quite difficult to read.  Furthermore,
  13         multilingual documentation makes for significant additional text.
  14
  15         With these considerations in mind, Mono will use external XML files
  16         for type documentation, rather than documenting the source inline.
  17
  18         Several tools will be created for managing, verifying, generating,
  19         and updating class library documentation, including:
  20
  21         <ul>
  22                 <li><a href="#docstub">docstub</a></li>
  23                 <li><a href="#docverify">docverify</a></li>
  24                 <li><a href="#docconv">docconv</a></li>
  25                 <li><a href="#docgen">docgen</a></li>
  26                 <li><a href="#monodoc">monodoc</a></li>
  27         </ul>
  28
  29 ** XML Documentation Files and Formats
  30
  31
  32 *** Monodoc XML
  33         This XML is similar to the XML documentation described in the
  34         C# standard, with added tags for internationalization and a
  35         slightly different structure.  Documentation and a DTD/Schema
  36         for Monodoc XML is forthcoming.
  37
  38         Monodoc XML does not contain any definitive type information,
  39         and is only useful in conjunction with the Type definition for
  40         whatever is being documented.
  41
  42         This XML could be generated by hand, by monostub, or by monodoc.
  43
  44 *** Assembly XML
  45         This XML is generated by combining runtime type information for
  46         an Assembly with a collection of Monodoc XML files.  The resultant
  47         XML (in the best of cases) contains both complete type and
  48         documentary information for each type in the assembly.
  49
  50         This XML contains enough information to be transformed into
  51         user-accessible documentation.  It is likely that scripts
  52         will be created to generate reference docs as HTML and other
  53         formats.
  54
  55         Documentation and a DTD/Schema for Assembly XML is forthcoming.
  56
  57 ** Documentation Tools
  58
  59 *** <a name="docstub">docstub</a>
  60         Given a type name and an assembly, generates stub Monodoc XML
  61         documentation for the type.  Optionally, docstub can attempt to
  62         populate initial documentation from an XML file in the format
  63         published along with the ECMA standard.
  64
  65 *** <a name="docverify">docverify</a>
  66         Given a Monodoc XML file and an assembly, verifies that the
  67         documentation matches the compiled type.  Checks signatures,
  68         parameters, et cetera.
  69
  70 *** <a name="docconv">docconv</a>
  71         Converts from Monodoc XML to the standard C# compiler-emitted
  72         XML format and vice versa.
  73
  74 *** <a name="docgen">docgen</a>
  75         Given an assembly and a collection of Monodoc XML files, creates
  76         an Assembly XML file containing all documentation and type information
  77         available.  This output is suitable for transforming into user
  78         documentation.
  79
  80 *** <a name="monodoc">monodoc</a>
  81         A GUI tool for documentation and translation, this encapsulates
  82         the capabilities of docstub, docverify, docconv, and docgen in
  83         a friendly user interface.  In addition, monodoc provides features
  84         to ease translation, such as side-by-side editing and coverage
  85         statistics.
  86
  87 ** Status and Roadmap
  88
  89 *** 2 January 2002
  90
  91         As I write the initial version of this document, very little has been
  92         implemented.  Currently, there is a:
  93
  94         <ul>
  95         <li>Preliminary version of the Monodoc XML format</li>
  96         <li>Preliminary version of the docstub utility</li>
  97         </ul>
  98
  99         Here's hoping for frequent, productive updates.
 100
 101 ** Get Involved
 102
 103         Help us define Mono's documentation structure!  Subscribe to
 104         <a href="http://lists.ximian.com/mailman/listinfo/mono-docs-list">mono-docs-list</a>
 105         and wade right in.