[Mono-list] More documentation info

[John Barnette]

Folks,

For those of you who have been following mono-docs, I recently posted an 
example of XML documentation, that, while similar to the output of csc 
/doc, is more easily read and hand-edited by humans.

A lot of folks have expressed concerns about using this schema, since using 
csc /doc allows interoperation with 3rd-party tools, and is included in the 
ECMA standard.

With that in mind, let me put forward a couple of points:

* This, it should be stressed, is a temporary solution to allow folks
   to write documentation by hand without going insane, while a GUI
   tool is developed.  In the long run, it will be quite useful for
   those (misguided ;-) folks who prefer to do their documentation
   by hand.  Once a GUI tool is usable, csc /doc XML will likely
   become the default format for all Mono API docs.

* Conversion to/from the output format of csc /doc will be trivial.
   Most of the tags are the same; types and members have just been
   reorganized and nested for human readability.

* As a counter to asterisk (1), I'd like to note that when a
   documentation GUI is available, all functionality of the GUI
   (coverage reports, stub generation, packaging, reporting)
   will also be available through command-line clients, for
   folks that don't want to use / can't run a GUI.

The current task list, as I see it:

1. (John) Complete documentation and schema for new XML format.
2. (Adam) Alter docstub to generate new-style stubs.

(at this point, people can start writing documentation!)

3. (Any)  Conversion scripts, new <--> csc /doc


One other note: I'd really like to get cracking on design/implementation of 
a GUI client for documentation/translation work.  Who's with me? ;-)


~ j.