README

Monodoc
-------

	This is the MonoDoc module.  It contains the documentation for
	the Mono class libraries, tools to produce and edit the
	documentation, and a documentation browser.

	The documentation browser consists of a library and two
	front-ends: a Gtk#-based one, and an ASP.NET-based version.
	
	This set of tools is under heavy development, please report any bugs 
	in the Mono/Doctools module of Ximian Bugzilla (bugzilla.ximian.com)

* Web Edition

	To run the web edition, copy the browser/web directory into
	a directory in your web server, for example:

		cd browser/web
		mono xsp.exe

	Then you can browse it:

		http://localhost:8080/index.html

* Gtk# Edition

    The Gtk# frontend is in Mono SVN in mono-tools/docbrowser

* Format

	The documentation in this module is in the format used by the
	ECMA specification.

* Layout

	The documentation is contained in the `class' directory, the
	documentation is done in a per-assembly basis.  The idea is
	that each one of the assemblies will become a documentation
	module, and then help browser will be able to aggregate
	multiple documentation modules when users install new
	assemblies on their system.

	Example, the class "System.IO.Path" is part of the corlib
	assembly, and its part of the "System.IO" namespace there.
	The documentation in english for it, will live in the
	following directory:

		class/corlib/en/System.IO/Path.xml

	Now, each "assembly" has a list of "pending" methods that must
	be documented, those live at the assembly level directory, in
	this case the "master" file for the corlib assembly will live
	in:

		class/corlib/mscorlib.xml

	This file is used to keep track of what needs to be
	documented.  The documenting tools can then be used to verify
	that everything is documented.   These files are generated by
	the mkmaster program.

	This is a small "snapshot" of what it might look like in a
	tree fashion (I can not draw nice trees):

		class/
			corlib/
				en/
					System/
					System.IO/
					System.Reflection/
				es/
				it/
				fr/
				de/
			System/
			System.Xml/
			System.Drawing/

* Editing tools.

	Monodoc contains a built-in editor for class library
	documentation.  Just click next to a node that you want to
	edit in the [Edit] button, and you will be taken to a
	graphical editor.

	Once you are done with all your edits, you can use the
	`File/Upload Contributions' option to submit your
	contribution. 

* Documentation tools.

	Mono classes are being documented in a different way than
	Microsoft suggests.  The reason obeys to the need to maintain
	multiple translations, and the fact that inline-documentation
	is better suited for explaining particular implementation
	details, or to communicate to someone reviewing/auditing the
	code the intentions behind the code.

	Adding inline documentation for the whole class library to the
	source code makes the source code harder to read.  It might be
	useful for small projects, but for large projects its not
	worth doing that way.

	The updater tool (located in monodoc/generator/updater.exe) can
	generate documentation stubs from assemblies.  Also, it can be
	used to update docs as changes are made to the assemblies,
	maintaining existing changes when appropriate.  It can also
	detect what has been removed from an assembly and mark it as
	deprecated or remove it completely.