doc/classlib-doc

   1 * Class Library Documentation
   2
   3 ** Summary
   4
   5         While using inline XML tags to document classes is certainly
   6         convenient, properly verbose documentation quickly overwhelms
   7         the code, making the source quite difficult to read.  Furthermore,
   8         multilingual documentation makes for significant additional text.
   9
  10         With these considerations in mind, Mono will use external XML files
  11         for type documentation, rather than documenting the source inline.
  12
  13         Several tools will be created for managing, verifying, generating,
  14         and updating class library documentation, including:
  15
  16         <ul>
  17                 <li><a href="#monodoc">MonoDoc - A graphical documentation editor and viewer.</a></li>
  18                 <li><a href="#mkmaster">MkMaster - A command line tool to feed stub information to MonoDoc.</a></li>
  19                 <li><a href="#aspnet">An ASP.NET documentation editor.</a></li>
  20                 <li><a href="#xsltool">An xsl tool to convert monodoc xml to html documentation.</a></li>
  21         </ul>
  22
  23 ** XML Documentation Files and Formats
  24
  25
  26 *** Monodoc XML
  27         This XML is Mono's documentation format. Documentation and a DTD/Schema
  28         for Monodoc XML is located in cvs and can be found <a href="http://go-mono.org/monodoc.dtd">here</a>.
  29
  30         This XML could be generated by MonoDoc or the ASP.NET client.
  31
  32         More about the XML format <a href="http://go-mono.org/monodoc-xml.html">here</a>.
  33 ** Documentation Tools
  34
  35 *** <a name="monodoc">MonoDoc</a>
  36          A graphical documentation editor and viewer.  Currently, MonoDoc
  37          consists of a Qt# application and is in heavy development.
  38
  39 *** <a name="mkmaster">MkMaster</a>
  40         This tool creates the Master.xml file that MonoDoc uses as a reference
  41         for documentation generation. This is a reflection engine that is used
  42         to gather metadata from assemblies and create an xml representation.
  43
  44 *** <a name="aspnet">ASP.NET</a>
  45         This tool is planned.
  46
  47 *** <a name="xsltool">An XSL converter</a>
  48         This tool is planned.  If someone wants to step forward and adopt this
  49         project, it would be very helpful ;)
  50
  51 ** Status and Roadmap
  52
  53 ***  16, September 2002
  54
  55 A preliminary version of MonoDoc is in Mono's cvs.  It is under heavy development.
  56 Once this is complete we will start documenting the API!
  57
  58 ** Get Involved
  59
  60         Help us develop Mono's documentation tools!  Subscribe to
  61         <a href="http://lists.ximian.com/mailman/listinfo/mono-docs-list">mono-docs-list</a>
  62         and wade right in.