Re: [DotGNU]C# documentation comments in pnetlib

[Stephen Compall]

Baron Schwartz <address@hidden> writes:

> I've been browsing through some of pnetlib and see that there's not
> much C# documentation comments in the code, though many files do
> have them.  My first thought was, "it doesn't matter since we'd just
> be duplicating the MS .NET Framework documentation if we DID put
> them in."

More fundamentally than the reasons you gave, MS .NET docs are not a
valid substitute for a free software project, because non-free
documentation is no substitute for free documentation.

> But on the other hand, those comments are used for a lot of stuff
> such as pop-up tips in IntelliSense in Visual Studio.  Someday, when

Ha ha.  IntelliSense :)

> there are more IDEs, that'd be nice to have in the pnetlib classes,
> too -- so many developers think it's indispensable to have those
> tips (we Vim users don't notice their presence ;-) Anyway, I could
> see lack of pop-up tips as a barrier to adoption.

Not just `IntelliSense' (ha ha :), but more importantly for generating
complete library references, so that no one need depend on the
non-free documentation.

> Two questions:
> 
> 1) does adding such documentation count as worthy of a patch?  I'd
> be willing to add them to the System.Xml classes, which I hope to
> contribute to.  It would help me learn these classes better.

Surely it does.  Good luck, if you decide to do it.

> 2) Are there any license issues?

Yes.

> Can we legally add similar or identical documentation as exists in
> the MS .NET documentation?

No.

Most importantly, just as with pnetlib code proper (wrt Rotor), you
must not refer directly to the MS documentation while writing doc
comments.  Instead, take notes of your own about the important
details, then write docs based on those notes.  Or, if feeling extra
adventurous, write them based on the code -- which may not do the
right thing.

I hate to pass the buck (who am I kidding -- I love to pass the buck),
but Rhys recommends that the original code writers not write the doc
comments, as they have been exposed too heavily to the MS
documentation, thus dirtying up the room too much.

--
Stephen Compall or s11 or sirian

"On a normal ascii line, the only safe condition to detect is a 'BREAK'
- everything else having been assigned functions by Gnu EMACS."
(By Tarl Neustaedter)

BATF Qaddafi MIT-LL SHA NATO bce TWA Centro Legion of Doom cybercash
South Africa Jiang Zemin Mena clones JSOFC3IP