"Lex Spoon" <lex at cc.gatech.edu> wrote:
	The difference between the comment collector and the hierarchy browser
	is subtle.  In one, you get a single text pane holding all the comments
	which you can then scroll through with the regular text scroller.  In
	the other, you get a list morph plus a text pane, and you can scroll
	through the items of the list.

No, not "CAN scroll" but "HAVE TO scroll".  It's a big difference.

Most classes don't have many ancestors.
The average depth over all system classes in Squeak 3.5 is 5.4;
the median is 6, and the maximum is 14.  (This doesn't count Object
or the classes above it in Squeak's hierarchy.)  In "user" code the
average depth is rather smaller.
The deepest chain I found was "EToyProjectQueryMorph class" and
most of the entries contributed nothing to the comment.  If I had
filtered out the metaclasses, the average depth would have been
rather smaller.

While some class comments are big, most of the class comments that
actually exist are not all that big.  Typically, you have
    Object
        MyBigIdea "with a really big comment"
          MyInterestingCase "with a small comment"
            MySpecialCase "with a small to medium comment"

	You might call this difference the amount of "flatness" in the browser. 

Note that I am NOT in any way shape or form against hierarchy.

	You are essentially proposing to have a flattened hierarchy
	browser (and a flattened method inheritance browser, I presume,
	for method comments).

Yes.

BUT note that this is not INSTEAD of the existing machinery,
but AS WELL AS.
	
	Personally, I tend to prefer more hierarchy rather than less, ...

I am not in the slightest arguing against hierarchical views.

All that I am saying is that SOMETIMES for SOME purposes they get
in the way.

	I like being able to see just the portion of the
	file I am working on without having to visually search.
	The downside is that you *only* see a limited amount of stuff at
	a time, and thus you can end up clicking a little more to move
	around.
	
Make that "clicking a LOT" and we're in 100% agreement.
But oddly enough, it's "search" which is precisely my point.

	Anyway, you apparently lean towards the opposite end of the
	spectrum from me.

For SOME purposes SOME of the time.

	You prefer to see more information at once,

Not quite.  I prefer to *choose* how much information to see
without clutter, instead of *always* having to use (a/lots of) narrow
window(/s).  If anyone wanted to add some kind of outline support to
ParagraphEditor, I'd cheer them on, because that would provide more
choices.

But there is something even more important than that.

The more important point is that Squeak's text editing tools don't
span multiple windows.  If I want to do searches, I can only search
in one window at a time.  If I want to know "where is this instance
variable documented", I can't just search for its name in "the"
class comment, but have to manually click through perhaps all of the
ancestral class comments.  In the same way, if some outline mode in
some editor stops me finding things I'm looking for just because the
occurrences happen to be folded up at the time, then I'm not very
happy with that editor.

Yes, I know about SystemDictionary>>browseClassCommentsWithString:
but it looks in too many classes.  And I don't want to keep building
a new interface window every time I search within a single group.

There are of course alternatives to "flattened" views, and I've just
hinted at one of them:  extend text search so that there is some way
of "chaining" to other (possibly new) windows.  Another might be to
exploit the GUI medium and have some sort of "fisheye" text where you
could drop text morphs into a container and have them automatically
blow up to legible size when the mouse was over them.  Another might
be to deliver a set of class comments (or method comments or other
closely related texts) as a tabbed bookmorph (if there were such a
thing as a tabbed bookmorph), as long as search starting in any page
in the book could take you to any other relevant page.

The "flattened" view is just the easiest one to build.
It took me all of 11 lines of code to extract the text I want:

    Class>>writeCommentOn: aStream
	(superclass isNil or: [superclass == Object])
	    ifFalse: [superclass writeCommentOn: aStream].
	aStream nextPutAll: self name.
	self category ifNotNil: [aStream nextPutAll: ' (';
				 nextPutAll: self category; nextPut: $].
	aStream cr; cr; nextPutAll: self organization classComment; cr.

    Class>>allComments
	|s|    |
	s := WriteStream on: (String new: 200).
	self writeCommentOn: s.
	^s contents

Hooking that into the Browser machinery is probably going to be about
6 lines of code; the trouble is I don't know just _which_ 6 lines or
_where_ yet.  But from playing with this in a Workspace, I can already
say "great, this really *IS* as handy as I thought it was going to be."

That's not to say that other approaches might not be better.