Initial commit of XML doc roadmap.

svn path=/trunk/mono/; revision=1783

1 files changed, 105 insertions, 0 deletions

diff --git a/web/classlib-doc b/web/classlib-doc
new file mode 100644
index 00000000000..49735af98b1
--- /dev/null
+++ b/web/classlib-doc
@@ -0,0 +1,105 @@
+* Class Library Documentation
+
+** Summary
+
+	<em>
+	[This documentation is in progress.  Comments to
+	<a href="mailto:jbarn@httcb.net">jbarn@httcb.net</a>.]
+	</em>
+	
+	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="#docstub">docstub</a></li>
+		<li><a href="#docverify">docverify</a></li>
+		<li><a href="#docconv">docconv</a></li>
+		<li><a href="#docgen">docgen</a></li>
+		<li><a href="#monodoc">monodoc</a></li>
+	</ul>
+	
+** XML Documentation Files and Formats
+
+	
+	*** Monodoc XML
+	This XML is similar to the XML documentation described in the
+	C# standard, with added tags for internationalization and a
+	slightly different structure.  Documentation and a DTD/Schema
+	for Monodoc XML is forthcoming.
+	
+	Monodoc XML does not contain any definitive type information,
+	and is only useful in conjunction with the Type definition for
+	whatever is being documented.
+	
+	This XML could be generated by hand, by monostub, or by monodoc.
+	
+	*** Assembly XML
+	This XML is generated by combining runtime type information for
+	an Assembly with a collection of Monodoc XML files.  The resultant
+	XML (in the best of cases) contains both complete type and
+	documentary information for each type in the assembly.
+	
+	This XML contains enough information to be transformed into
+	user-accessible documentation.  It is likely that scripts
+	will be created to generate reference docs as HTML and other
+	formats.
+	
+	Documentation and a DTD/Schema for Assembly XML is forthcoming.
+	
+** Documentation Tools
+
+	*** <a name="docstub">docstub</a>
+	Given a type name and an assembly, generates stub Monodoc XML
+	documentation for the type.  Optionally, docstub can attempt to
+	populate initial documentation from an XML file in the format
+	published along with the ECMA standard.
+	
+	*** <a name="docverify">docverify</a>
+	Given a Monodoc XML file and an assembly, verifies that the
+	documentation matches the compiled type.  Checks signatures,
+	parameters, et cetera.
+	
+	*** <a name="docconv">docconv</a>
+	Converts from Monodoc XML to the standard C# compiler-emitted
+	XML format and vice versa.
+	
+	*** <a name="docgen">docgen</a>
+	Given an assembly and a collection of Monodoc XML files, creates
+	an Assembly XML file containing all documentation and type information
+	available.  This output is suitable for transforming into user
+	documentation.
+	
+	*** <a name="monodoc">monodoc</a>
+	A GUI tool for documentation and translation, this encapsulates
+	the capabilities of docstub, docverify, docconv, and docgen in
+	a friendly user interface.  In addition, monodoc provides features
+	to ease translation, such as side-by-side editing and coverage
+	statistics.
+	
+** Status and Roadmap
+
+*** 2 January 2002
+
+	As I write the initial version of this document, very little has been
+	implemented.  Currently, there is a:
+	
+	<ul>
+	<li>Preliminary version of the Monodoc XML format</li>
+	<li>Preliminary version of the docstub utility</li>
+	</ul>
+	
+	Here's hoping for frequent, productive updates.
+
+** Get Involved
+
+	Help us define Mono's documentation structure!  Subscribe to
+	<a href="http://lists.ximian.com/mailman/listinfo/mono-docs-list">mono-docs-list</a>
+	and wade right in.
\ No newline at end of file