[Mono-docs-list] Proposed human-readable XML

[John Barnette]

At 03:44 PM 3/13/2002, Miguel de Icaza wrote:
>Hello John,
>
> > Attached is an example of XML documentation in a form that I'd like to use
> > for all our human-editable API docs.  A couple of advantages:
> >
> > * Understandable enough to hand-edit
> > * Contains (almost) no information duplicated in assembly metadata
> > * Shares many tags and conventions with the XML documentation schema
> >    described in the ECMA C# standard (translation back and forth will
> >    be trivial)
> >
> > Thoughts, please.  If this is worthwhile (and I get a response from the
> > list ;-), an XSD, tag manual, stub generator, and translators to/from the
> > csc generated output style will follow as quickly as I can crank 'em out.
>
>As I mentioned yesterday, I had my reservations about coming up with a
>new file format for documentation, my rationale was:
>
>         * It is worth getting a new file format, if the existing file
>           format is not complete enough or is missing crucial features.
>
>One other reason to use the CSC format (I am not sure if this is the
>same as the XML API documentation) is that many developers have already
>written CSC-like documentation (me included) in the source code, and we
>would like an easy way to extract those.

Hey Miguel,

I agree with most of what you're saying, with the exception of a point 
addressed below. :-)  I believe, though, that proving a schema that is 
reasonable for hand-editing (all we can do right now) is important, so we 
can start the documentation process sooner rather than later.  As Nick 
mentioned in his comments to the list, using this more readable version 
temporarily allows us to start documenting quickly, easily switch between 
formats, and provides an easier path for misguided hand-documenters in the 
future. ;-)

>XML is not supposed to be hand-edited anyways.

I don't necessarily agree with this.  After all, inline C# comments are 
XML.  Large XML files are certainly difficult to read and edit, but there 
will always be folks who would rather do their documentation and 
translation work in EMACS rather than in our shiny GUI.

My current thinking is this: A GUI is good; I can't wait to build and use 
it.  A GUI is necessary.  A GUI should not be the only way to generate, 
validate, or create documentation.  TMTOWTDI, baby.


~ j.