[Mono-dev] Contributing Code for ObservableCollection

[Brian O'Keefe]

I've made the suggested changes:

1) Pulled the XML comments out to a separate file (but not in monodoc yet).

2) I moved the shared methods out to a static class.  At the same time, I
discovered that I forgot to add my test classes to
WindowsBase_test.dll.sources, so I did that too.

3) I added a test the calls BlockReentrancy twice.  The test passes on MS
.Net and Mono, so I assume the implementation is valid.  It does seem like a
fairly unintelligent implementation to me.  I suppose they're protected so
that OnCollectionChanged can be replaced in subclasses without needing a
separate reentrancy block, but it's not terribly obvious why that would be
useful.  The conclusion was that calling BlockReentrancy twice will indeed
give you the same object back, and it also prevents the CollectionChanged
event from firing.

I'll attach the replacement patch.

~Brian

On Tue, Nov 4, 2008 at 6:40 PM, Jonathan Pryor <jonpryor at vt.edu> wrote:

> 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
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.ximian.com/pipermail/mono-devel-list/attachments/20081104/f789143c/attachment-0001.html 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: WindowsBase_bokeefe.diff
Type: application/octet-stream
Size: 68343 bytes
Desc: not available
Url : http://lists.ximian.com/pipermail/mono-devel-list/attachments/20081104/f789143c/attachment-0001.obj