I think that class comments should come up automatically (perhaps in a
separate pane) when the class level is reached in the browser. I don't
think it helps very much to have it entangled with the instance/class view
distinction. I generally want to keep on reading them (especially if class
comments were more like real documentation) while perusing the methods, etc.

Cheers,

Alan

-----
At 7:53 AM -0800 2/9/00, Norton, Chris wrote:
>Hi Folks.
>
>~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>> Dan Ingalls wrote:
>>
>"I agree pretty much.  While it should not include implementation details,
>this is definitely the place for overall implementation approach (the
>architecture).  Also, sometimes it can be nice to have one or two sample
>doits in the class comment to save having to browse deeper to find
>examples."
>
>Tim Rowledge replied:
>"I'd strongly support the inclusion of overall architecture and some
>examples in the class comment, as well including a reasonable explanation of
>what the class is _intended_ to do. That would at least offer a modicum of
>help when trying to debug. It's amazing how easy it is to write a beautiful
>explanation of how a class works, what it inherits from etc and yet still
>leave the reader completely in the dark about the intended usage.
>
>> Oh, and I'd suggest a URL for further documentation info; perhaps this
>> could even be automated and a page built for each class on a swiki? That
>> would facilitate public enhancements and so on for times when one does
>> have a network connection open."
>~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
>I agree as well with Dan's points (especially about architecture).  If a
>class is intended to be _abstract_ or _private_ and it is not named in a way
>that points this out, then the class comment should do so.  Doits can also
>be very good in some class comments.  A good example would be a doit in the
>class comment for a game that starts out game.  I also like the idea of a
>class comment initial template, so long as the user has the option of not
>using the template (there are always exceptions to any rule :-).
>
>As far as incorporating URLs into the source code...  Well, that may make
>the code obsolete.  URLs, in my experience, are notoriously short lived.
>Unless the URL targets a main hub, like www.cnn.com, it is likely that it
>will become obsolete long before Squeak does.  However, I think your idea,
>Tim, is a good one.  There is a "hyperfind" mechanism built right into
>Squeak.  We could be using that in the source code to relate comments,
>ideas, ways of doing things, etc.  This mechanism could add another
>dimension to our coding experience (if done well).
>
>Just tossing in my 2 cents...  :-)
>
>BTW:  I really think that adding internal documentation (comments) to Squeak
>is a Great Idea.  I will gladly read over any comments that you good folks
>want to add to the product.
>
>Cheers!
>
>---==> Chris