[Mono-list] About documentation

[Miguel de Icaza]

Hello,


> Yes, of course, I have downloaded yet that module when I wrote the mail.
> But I didn't found anything else than the directory-structure, empty xml
> files (I suppose they will have the documentation) and the tools. My
> question is about what documentation (API-docs) is written yet and if I
> can see it before I start writting any class reference.

The module you downloaded should have roughly 18 megs of documentation. 
That documentation comes from the ECMA specification, and only covers
the classes that are part of ECMA.

I have now checked into MonoDoc the following README file that should
help us stay more organized in the future ;-)



Monodoc
-------

	This is the MonoDoc module.  It contains the documentation for
	the Mono class libraries as well as tools to produce and edit
	the documentation.

	Hopefully we will also soon have a documentation browser.

* 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.

	We are in the process of developing a tool called `monodoc'
	which is a Gtk#-based documentation editor that would simplify
	the editing of the ECMA-xml documentation.  This tool is
	currently not finished, but it lives in tools/gtk-monodoc.


* 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.

	Adam contributed a tool called `MkMaster' which will take an
	assembly and will generate a "tree" of the pieces that must be
	documented.