"Lars Nilsson" <lars at cymfony.com> wrote:

> In quite a few cases, gaining the knowledge that is equivalent to what is
> given in class comments similar in form to what is given above can be gained
> by just looking at the name of the class and the messages it contains. 

I disagree.  Reading through class Class or ClassDescription can be
quite a chore, and yet it's comment points out just what the big deal
about them is.  I think you are talking about *bad* comments.  :)


> But
> again, this knowledge doesn't necessarily make it much easier to actually
> make use of the class. And this is what I personally feel is missing. Either
> comments describing the general use of the class (might not describe every
> single function, but should describe the most frequently used ways of
> working with the class), or as someone has mentioned a while back on this
> list, a set of class messages (not instance messages) illustrating the use
> by example.
> 

Yes, examples are missing.  But we need comments as well, don't you
agree?

And as food for thought, examples of using a *class* aren't always the
right question.  "How do you use Point?" Uhhh....  "How do you use the
graphics library?"  Ahh, now we have a good basis for making examples. 
We also have a large enough problem, that it's worth writing an essay or
a book chapter about it, in addition to just sprinkling around some
example code....

Lex