[Mono-list] ECMA compliance

[John Barnette]

> > The important thing is encoding - what encoding to use.
> > Many widely-used code editors are not "Unicode-enabled", moreover some
> > have problems with anything beyond 7-bit charset.
> > So maybe it's better to have only English version embedded, and separate
> > files with translation.
>
> I think we can take this decision based on whether we should split out
> the documentation out or not.   If we can split out the documentation, I
> would advocate the use of specialized tools that would assist in the
> translation process.

Currently, I'm inclined to say that we should split out API documentation
for the core.  While the compiler should certainly support inline
documentation as laid out in the C# spec, I think the advantages of
separating the documentation for the core libraries (where, as Miguel said,
it's possible that we would have 40 different locale translations) are too
large to ignore.

I very much doubt that I will externalize the API docs for any small
programs I write, but for a large, eventually-stable set of work like the
core libs I think it's a good idea.

> Come to think of it, it would be possible for the documentation tool
> *AND* the translation tool to use System.Reflection to extract all the
> public members, and display which ones need documentation to be written
> (something that right now with source code is really hard to do, as we
> have to go manually to each file and verify everything).
>
> A Windows.Forms client could be able to track everything: summary,
> remarks, parameter description for each argument and would also help in
> that people would not have to write the XML strings ever, they will just
> cope with a specialized client that presents the best possible UI to
> document something.

This would be awfully nice.  In this case, we have an easy, visual way to
check sync and see what remains to be documented.  Plus, running various
offline tasks would be easy as part of the test/qa builds.  Generating
documentation todo lists or doc coverage counts for various supported
languages, for example.

If anybody's interested, I'll try to draft a proposal for a reasonable XML
DTD/Schema for external API documentation files in the next day or two.


~ j.