On Sun, May 02, 2010 at 10:16:48PM +0000, Hannes Hirzel wrote:
> Thank you David for this contribution. I assume the class comments are
> in there. We just do not see them in the diff...

Yes the class comments are in the updates. Actually, this illustrates
a very interesting artifact of Monticello. The creator of Monticello
was not very interested in class comments, as you can plainly see by
browsing the actual Monticello code. This seems to have created a
"blind spot" with regards to documentation, as Monticello browsers and
tools do not even bother to display any changes to class comments.

This highlights two areas in which documention improvements are badly
needed:

First, the Monticello classes themselves are a vast wasteland of
undocumented functionality in a very important part of the system.
I really don't know how most of this stuff works, and I'll bet that
I am not the only one who is confused. Adding class comments for
Monticello classes would be very helpful.

Second, with respect to the tools, fixing Monticello to display
changes to class comments both in the browsers and in the diffs
posted to the mailing list would be a Really Good Thing. If we
don't have this, then we lose visibility for changes to the
comments. Personally, I think that the comments are just as
important as the actual implementation, so any changes to
comments should be just as visible as changes to the code.

Dave