I made a run at this a while back but had to pull off of it before I got
things whipped into shape enough to put into the update stream. I have
coverage of some 100+ classes right now - which I just need to edit down
and complete. Since it seems that I won't get it done any other way
right now, I could finish off a few classes each day and send them on to
you to be checked over and entered into the update stream.

Stefan Matthias Aust wrote:
> 
> >>It's not documented in the "comment" for the class.
> 
> Unfortunately, too many classes don't have comments.  Is there anybody who
> wants to step in an write and provide additional class comments?  In
> exchange, I'd make sure that they get added as candidates for the update
> stream.
> 
> However, we should first agree upon a common format.  Some (old) class
> comments use "I" to refer to the class.  Other comments use "This class" or
> use the class name "ProtoObject establishes". I'd vote for the later two
> variants.  

Agreed. I think I would normally prefer to use the class name - like
"ProtoObject defines/establishes/creates/represents/...".

>           The comment should be sort and should clearly describe the
> classes purpose without going too much in detail.  For classes with
> instance variables, I'd prefer if their purpose is also described by naming
> the expected class and its purpose, for example
> 
> session - a HttpSession, the current session as decoded from the cookie
> 
> The class comment should not contain implementation details, comments,
> development history or examples of usage. The latter is better documented
> in class methods called exampleX (X being a number) in a "examples"
> category.  Additional documentation should be put into appropriate class
> methods in a "documentation" protocol.

I mostly agree - except for classes that were explicitly created to
define and manipulate instances whose precise internal representation is
important for proper general usage -- like Float or SmallInteger -- or
for classes where knowledge of the algorithm used to implement the class
is needed by the user of the class to decide when the class is
appropriate to use and when it is not - like Random.

-- Dwight