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.
_______________________________________________
Mono-list maillist - [EMAIL PROTECTED]
http://lists.ximian.com/mailman/listinfo/mono-list
