[Mono-list] ECMA compliance

[John Barnette]

> > Well, for one it is really easy to manipulate and merge information in
> > XML. Manipulating and merging information into source code is a whole
> > different game.
>
> But I mean using already extracted documentation.
> That is, what's the difference between:
> a) Always extracting Master File (en-US) from sources before using it;
>  and
> b) Maintaining it manually as a separate file;
>
> Also, I'm worried about people who will read the *sources*,
> they will need the comments, right?

Okay, kids, how does this grab you?

Proposed:
By convention, en-US API documentation resides in the source, where it can
be read by coders and serve (in most cases) as the definitive version of the
docs.  Differing from Microsoft's approach a tool will be provided so that,
given a .cs file and a compiled assembly, an XML file in the same format as
other languages can be produced.

Similarly (or perhaps this can serve as the aforementioned tool) the Mono C#
compiler, when directed to produce documentation, should produce something
closer to the ECMA schema (but likely a superset) rather than strictly
adhering to Microsoft's method.

I would like for generated documentation, irregardless of i18n concerns, to
contain all relevant information on a class, struct, or enum, rather than
having to dig into the assembly each time standalone docs are necessary.


~ j.