[Mono-dev] Contributing Code for ObservableCollection

[Jonathan Pryor]

On Tue, 2008-11-04 at 16:39 +0000, Alan McGovern wrote:
> 1) Xml comments are a no-go in the source files. If you want to commit
> documentation (which is always appreciated!) you should add it to
> monodoc and submit it as a separate patch. It should be possible to
> import your XML comments into monodoc automatically so you don't have
> to re-type them. Once they've been imported to monodoc, you'll have to
> strip them from the source files.

Which brings up an interesting question... :-)

We now have a `make doc-update` target in the makefiles, which will
generate/update the monodoc documentation into a Documentation directory
(at least in mcs; olive doesn't have that support, but iirc WindowsBase
will soon be moved into mcs so this still applies).

Now, mdoc-update (which generates/updates monodoc documentation) has XML
documentation import support via the -import argument.

And gmcs has the -doc flag to generate XML documentation.

Putting these together, and it's quite trivial to always generate an XML
documentation file and have `make doc-update` import this file (~3 LOC
to the current build system, iirc).

There is just one "minor" problem with it: importing is currently an
overwrite operation, not an appending operation.  Consequently, if you
have existing documentation, then import documentation for the *same*
member, you lost the original documentation.

(Normally this is the right thing to do, as if you always appended you'd
always get duplicated documentation each time you imported...)

The problem in this case is mscorlib (and possibly other assemblies; I
only looked at mscorlib): there is XML documentation on some members
within the source files that would replace the existing documentation
(which was imported from the ECMA standard), and the imported version is
*far* worse than the current documentation.

Case in point: mcs/class/corlib/System.Reflection/CallingConventions.cs,
which contains <summary/> elements (i.e. an empty element), thus
replacing *actual* documentation with *nothing*.  Oops.

So much as I would *love* to enable XML documentation importing by
default (thus allowing people to write documentation *either* within
monodoc format OR with XML documentation comments), this isn't currently
possible because the net result would be detrimental.

The solution, obviously, is to go through the documentation and remove
all instances where the existing documentation is better than the XML
doc comments, and either move the documentation into doc comments or
remove the doc comments...

But in the absence of anyone working on this (and I'm not currently
working on this), it's only a long term goal...

 - Jon