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

[Miguel de Icaza]

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.

So on top of my regular concern, we have this one.  Granted, this
concern is not an issue if we have a tool that can map between the
formats easily, but then again, that raises the question of why having a
compatible, but different file format.

XML is not supposed to be hand-edited anyways.

I just wanted to voice these opinions, I will go with whatever the rest
of the group feels more comfortable with, but I think we should keep
these things in mind.

Miguel.