[Mono-docs-list] Proposed human-readable XML
Wed, 13 Mar 2002 16:47:58 -0700
At 03:44 PM 3/13/2002, Miguel de Icaza wrote:
> > 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.
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
>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.