mono/web/classlib-doc

* Class Library Documentation

** Summary

	While using inline XML tags to document classes is certainly
	convenient, properly verbose documentation quickly overwhelms
	the code, making the source quite difficult to read.  Furthermore,
	multilingual documentation makes for significant additional text.
	
	With these considerations in mind, Mono will use external XML files
	for type documentation, rather than documenting the source inline.
	
	Several tools will be created for managing, verifying, generating,
	and updating class library documentation, including:
	
	<ul>
		<li><a href="#monodoc">MonoDoc - A graphical documentation editor and viewer.</a></li>
		<li><a href="#mkmaster">MkMaster - A command line tool to feed stub information to MonoDoc.</a></li>
		<li><a href="#aspnet">An ASP.NET documentation editor.</a></li>
		<li><a href="#xsltool">An xsl tool to convert monodoc xml to html documentation.</a></li>
	</ul>

** XML Documentation Files and Formats


*** Monodoc XML
	This XML is Mono's documentation format. Documentation and a DTD/Schema
	for Monodoc XML is located in cvs and can be found <a href="http://go-mono.org/monodoc.dtd">here</a>.

	This XML could be generated by MonoDoc or the ASP.NET client.

	More about the XML format <a href="http://go-mono.org/monodoc-xml.html">here</a>.
** Documentation Tools

*** <a name="monodoc">MonoDoc</a>
	 A graphical documentation editor and viewer.  Currently, MonoDoc
	 consists of a Qt# application and is in heavy development.

*** <a name="mkmaster">MkMaster</a>
	This tool creates the Master.xml file that MonoDoc uses as a reference
	for documentation generation. This is a reflection engine that is used
	to gather metadata from assemblies and create an xml representation.

*** <a name="aspnet">ASP.NET</a>
	This tool is planned.

*** <a name="xsltool">An XSL converter</a>
	This tool is planned.  If someone wants to step forward and adopt this
	project, it would be very helpful ;)

** Status and Roadmap

***  16, September 2002

A preliminary version of MonoDoc is in Mono's cvs.  It is under heavy development.
Once this is complete we will start documenting the API!

** Get Involved

	Help us develop Mono's documentation tools!  Subscribe to
	<a href="http://lists.ximian.com/mailman/listinfo/mono-docs-list">mono-docs-list</a>
	and wade right in.