[squeak-dev] [class comments] Kernel-Classes

The first category in my image with uncommented classes is Kernel-Classes. I'm cautious about presuming to explain
things in here, so if you can, please provide suitable class comments by committing or by replying to this thread.
Otherwise I press on, knowing that comments can be improved later.

I want to ask about ClassOrganizer's comment, by NS 4/6/2004:

   "I represent method categorization information for classes.  The handling of class comments has gone through a
tortuous evolution.   Grandfathered class comments (before late aug 98) have no time stamps, and historically, fileouts
of class comments always substituted the timestamp reflecting the author and date/time at the moment of fileout; and
historically any timestamps in a filed out class comment were dropped on the floor, with the author & time prevailing at
the moment of filein being substituted.   Such grandfathered comments now go out on fileouts with '<historical>'
timestamp; class comments created after the 8/98 changes will have their correct timestamps preserved, though there is
not yet a decent ui for reading those stamps other than filing out and looking at the file; nor is there yet any ui for
browsing and recovering past versions of such comments.  Everything in good time!"

Isn't ClassOrganizer about managing the class categories that we see in the left two panes of the package pane browser ?
Why does the above focus so much on

Doh! This was to be sent at another time. Oh well, continuing:

Why does the ClassOrganizer comment focus so much on class comments ? The info is rather useful but is it in the right
place ?

On 19.08.2009, at 20:29, Simon Michael wrote:

> Doh! This was to be sent at another time. Oh well, continuing:
>
> Why does the ClassOrganizer comment focus so much on class  
> comments ? The info is rather useful but is it in the right place ?


The actual categorization is handled by Categorizer. The  
ClassOrganizer subclass only extends this with class comments, so it's  
natural the focus is on the extended functionality.

Still, this could be mentioned if it helps people understanding.

- Bert -

Bert Freudenberg wrote:
> The actual categorization is handled by Categorizer. The  
> ClassOrganizer subclass only extends this with class comments, so it's  
> natural the focus is on the extended functionality.

Thanks. That makes me want to rename ClassOrganizer; would this be

- a good idea

- warranted, but too disruptive to be worthwhile

- unwarranted, because.. ?

On 19.08.2009, at 22:14, Simon Michael wrote:

> Bert Freudenberg wrote:
>> The actual categorization is handled by Categorizer. The  
>> ClassOrganizer subclass only extends this with class comments, so  
>> it's  natural the focus is on the extended functionality.
>
> Thanks. That makes me want to rename ClassOrganizer; would this be
>
> - unwarranted, because.. ?


... because its purpose is to keep a class organized. It inherits the  
ability to categorize and extends it with class specifics. What's  
wrong with that?

- Bert -

Bert Freudenberg wrote:
> ... because its purpose is to keep a class organized. It inherits the  
> ability to categorize and extends it with class specifics. What's  
> wrong with that?

Well, I just heard you say "The ClassOrganizer subclass only extends this with class comments". I guess I misunderstood.
If I read more code I can find out for sure. *Something* seems unclear with either the class names or the existing class
comment in these three:

   Categorizer
    BasicClassOrganizer
     ClassOrganizer

I think the second is actually the one that deals with class comments. (How apropos that I picked these..)

Well, right now I'd comment these something like so:

Categorizer: I represent an easily-manageable association of category names to element objects. See my documentation
method for more.

BasicClassOrganizer: I represent a Class which has a comment and a category. (Move most of existing ClassOrganizer
comment here.)

ClassOrganizer: I represent a Class whose category can be easily managed.

On 19.08.2009, at 22:53, Simon Michael wrote:


Well, yes, BasicClassOrganizer was introduced relatively recently  
(that is, in the last 10 years, not 30 years ago) to hold the code  
common to regular and pseudo classes. The comments might not reflect  
that.

- Bert -