I agree.  I'd also like to see error messages get their own window instead of
getting written to the CodePane of the Browser.  It's annoying to have to delete
them all the time.

==JB==


Alan Kay wrote:

> 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