[Mono-list] XML Documentation: A manifesto

[John Barnette]

;-)

* Class Library Documentation

** Summary

	[This document is in progress.  Comments to mono-docs-list@ximian.com.]
	
	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:
	
	- docstub
	- docverify
	- docconv
	- docgen
	- monodoc
	
** 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

	*** docstub
	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.
	
	*** docverify
	Given a Monodoc XML file and an assembly, verifies that the
	documentation matches the compiled type.  Checks signatures,
	parameters, et cetera.
	
	*** docconv
	Converts from Monodoc XML to the standard C# compiler-emitted
	XML format and vice versa.
	
	*** docgen
	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.
	
	*** monodoc
	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:
	
	- Preliminary version of the Monodoc XML format
	- Preliminary version of the docstub utility
	
	Here's hoping for frequent, productive updates.

** Get Involved

	Help us define Mono's documentation structure!  Subscribe to
	http://lists.ximian.com/mailman/listinfo/mono-docs-list
	and wade right in.


~ j.