[Mono-dev] Contributing Code for ObservableCollection

[Miguel de Icaza]

Hello,

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

Some of the documentation in Mono's source comes from the early days in
the project when we had not yet decided to put the documentation outside
the source code, so all of that documentation should be considered
stale.

There are a handful of exceptions, but they are exceptions.

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

Agreed.

We need to either assume that all the docs-in-source code is worthless
at this point and scrub it from the source code (or if someone feels bad
about something getting lost, that person should volunteer and move that
documentation to the external files).

Once we have a clear baseline ---I thought we did, but you just proved
that my assumption was wrong--- then we can start thinking about mixing
it up. 

My feeling is that for the class libraries that we author and maintain
we do not want to put inline documentation, just for the sake of
consistency.

Miguel.