[Mono-list] More documentation info
Tue, 12 Mar 2002 19:10:02 -0700
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
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? ;-)