[Mono-list] ECMA compliance

[Serge]

NDoc's author is about to extend the tool to support custom transforms.
Basically NDoc takes XML docs + assembly and generates MSDN style
documentation.
If/when custom transformations will be implemented perhaps the tool will
serve our needs, so we don't even have to invent some other format.
So, maybe it's worth to get in touch with Jason Diamond (NDoc author) to
work together in that direction.

Miguel's point about embedded comments (introducing extra noise, while
primary interest is implementation) makes sense either. Now I really don't
know :-)
One counter point is that automated stripping of comments from sources is
easier than placing them back ;-)



----- Original Message -----
From: "John Barnette" <jbarn@httcb.net>
To: "Serge" <serge@wildwestsoftware.com>; "Miguel de Icaza"
<miguel@ximian.com>
Cc: <mono-list@ximian.com>
Sent: Friday, November 23, 2001 11:59 PM
Subject: RE: [Mono-list] ECMA compliance


> > > 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.
>
>