Commenting class category

Hi all

All class should have a comment, as methods... ok
But I find class categories too (and method categories maybe). It
might be a quicker way to have a global vision of a system. Maybe this
is done (sort of) in one or the the most important "class" of the
category.

For instance, I find the seaside-callbacks category would be better
explained in its globality first. Class comment provide then more
precise information (especially when there is a hierarchy).

Do you think it would be useful too? I don't know if it's doable. An
easy way would be to add a empty class dedicated to wrinte comments
...

Just a thought :)

Cédrick

"cdrick" <[hidden email]> wrote

> For instance, I find the seaside-callbacks category would be better
> explained in its globality first. Class comment provide then more
> precise information (especially when there is a hierarchy).
>
> Do you think it would be useful too?

Useful? I would say essential. At the level of package & class category. In
order of usefulness, imho:

- package description
   - class category description
      - class & method category description

> An
> easy way would be to add a empty class dedicated to wrinte comments

Are packages and class-categories not first-class objects in squeak?

Sophie

>
> - package description
>    - class category description
>       - class & method category description
I'd like method categories to be category-tags

> Are packages and class-categories not first-class objects in squeak?
>

I don't think they are. There are SystemOrganizer and ClassOrganizer
but I don't find proper class for categories and Package. Somebody
else may answer here.

Cédrick

"cdrick" <[hidden email]> wrote

>>       - class & method category description
> I'd like method categories to be category-tags

So one method can be in many categories? I agree.

>> Are packages and class-categories not first-class objects in squeak?
>
> I don't think they are. There are SystemOrganizer and ClassOrganizer
> but I don't find proper class for categories and Package.

Ouch!

Sophie

> >>       - class & method category description
> > I'd like method categories to be category-tags
>
> So one method can be in many categories? I agree.

yep. Not suitable for all categories, but nice for private,
*monticello-extensions...

>
> >> Are packages and class-categories not first-class objects in squeak?
> >
> > I don't think they are. There are SystemOrganizer and ClassOrganizer
> > but I don't find proper class for categories and Package.
>
> Ouch!

Yep, that's why  I asked :)  but only newbies seems interested in that ;)

Actually, I'd like a browser, where whatever you select, you see the
comment first (could be a "newbie" or "discovering" mode).

- Selecting a class-category would show category comment (missing now)
- Selecting a class would show the comments in a separate pane, right
to the code pane.
- method-category and method comment could be accessible like a tooltip...

All could be certainly done as an experiment in OB, but there is no
way actually to have class category comments, and even if less
important to me, method category ones. Having category-tags sould be
even more difficult.

Cédrick

 Cédrick

Your suggestion of Documentation classes comes but one month after I
suggested the very same. Since each class in squeak may nominate its
#compilerClass and #parserClass it is possible to override these in such
a way as to ignore the method text.

I liked the idea but had several questions as to how to make the idea
work well. I had no replies to these questions, but there was some
debate as to the concept. (If you look in older versions of Sake, in
http://www.squeaksource.com/Sake you will find an implementation lurking
in there some where as SakeDocumentation)

Question 1. As far as my experiments show overriding #compilerClass to
point to a null compiler works. However it only works for instance side
methods. I wanted to know where one can select the #compilerClass for
class side methods.

Question 2. With this scheme no one tells "Shout", so it continues to
try and auto format the text thinking it is a normal method. Is there a
way to make shout aware on a per-class basis what language it is
highlighting.

My personal conclusion was to experiment with the idea to see how useful
it was within a particular domain... my experiment simply causes the
compiler/parser to ignore code after a line consisting of """""".

My second idea is to use the symbol ˚ in methods that are documentation,
such that #task˚ documents #task.

again this is all experimental.

You can get the code to experiment yourself by loading Kernel-Ext from
package 311 on squeaksource.

best regards

Keith

"Keith Hodges" <[hidden email]> wrote

> Your suggestion of Documentation classes comes but one month after I
> suggested the very same.

Newbie alert .... Why not make package and class-category proper objects
with their own documentation? Is it too far-reaching a change? Or would MC
not handle them since they are not classes or methods? Do those who know the
Squeak image well think that would be a bad move? Are there some other good
reasons to not go that route? All of the above? :-)

> Since each class in squeak may nominate its
> #compilerClass and #parserClass it is possible to override these in such
> a way as to ignore the method text.

Would that be needed? If these "documentation classes" are used as pure
"comment-holders", one for each package & class category, would the
class-comment field not suffice? The creation dialog for package / category
could directly require a non-empty package/category doc string in addition
to the name, creating the comment-holder class with some standard name
behind the scenes (always editable later in that class' comment).

- Sophie

Package has become a proper object, and the class categories have been replaced with Namespace, which are also proper objects.

I haven't touched method categories at all, but they are also a candidate for refactoring.

Note that MC does not work at all with my implementation.

Gulik.

--
http://people.squeakfoundation.org/person/mikevdg
http://gulik.pbwiki.com/

On Sun, Feb 10, 2008 at 08:16:53PM -0600, itsme213 wrote:
Long reply. I've worked with the categorizer recently, so I
should at least tell you how it works.

In Squeak, Classes are objects, methods are objects, but
categories are not. Categories are implemented interestingly.
See Categorizer and subclasses. Categorizer stores two lists of
Symbols; one is the list of all the categories, the other is the
list of all the class names or method names, arranged so that
all the names in the first part of the list are in the first
category, the next few methods are in category 2, and so forth.
So all the categories are is a symbol in a special list, with
the mapping to classes and methods is maintained by other
entities.

How would changing this work? Mostly, Browser would have to be
changed significantly. OmniBrowser would probably be easier to
adapt, but I have only worked with Browser, so I cannot comment.

Also, if not done properly, it would be quite possible to
completely break the tools while transitioning from Categorizer
to Namespace/Category or whatever would replace this. Thus,
making this transition could involve a period where using any
of the browsers was impossible.

Third, to get it used, you would have to get it into a well-used
image.

This would be an idea that would fit nicely with Gulik's work on
namespaces, as Namespaces are much like reified Categories.

I don't know whether incorporating this into MC would work
nicely or not. MC was extended rather gracefully to support
traits, so categories could probably be added similarly.

So, all-in-all, it's not a bad move, just that not many people
have messed with squeak's code model in release images. However,
Traits showed us that it is not forbidden, and if it works,
changes to the code model can make it into a release image. It
would be good to do, since having eyes actively watching over
the core code and improving it would make the kernel much more
modular.

--
Matthew Fulmer -- http://mtfulmer.wordpress.com/
Help improve Squeak Documentation: http://wiki.squeak.org/squeak/808

Hi Keith,

"Keith Hodges" <[hidden email]> wrote in message
news:[hidden email]...
To prevent Shout from styling these non-normal methods...

Look for all the implementors of #shoutAboutToStyle:
Make them answer false if the compilerClass of the class being browsed is
Null

e.g. in Browser>>#shoutAboutToStyle:  add the following line...
     self selectedClassOrMetaClass compilerClass ifNull: [^false].

Cheers,
Andy

> Your suggestion of Documentation classes comes but one month after I
> suggested the very same.

Oh funny... maybe I read it quickly and got the "inspiration" from that :).

The thing is I always find there are too much click to see a class
comment (one more in OB)... I'd like comments to spring to my face :)
and stay there as long as I use a given class...

really put anything in the comments, wich is not possible right now
("" inside a method comment is problematic)

What I'd like is a quicker ways to access them, like a tooltip. A
method-category comment could held all method comment it contains...

Thanks for the precisions Keith :)

"cdrick" <[hidden email]> wrote

> The thing is I always find there are too much click to see a class
> comment (one more in OB)... I'd like comments to spring to my face :)

One useful keyboard-only trick is to use e-completion. If you type in a
(partial) class name and hit cntrl-space you get a list of completions,
(n)arrow down to the one you want, arrow right -> will show the class
comment (it will disappear when you hit Esc). It does similar things for
message completions showing  the method body or list of implementors. Very
convenient.

http://uncomplex.net/ecompletion/screenshots.html

It would be great (reduce click-count and browser-count) if it did that
through more than one layer of indirection e.g.
from a list of classes, to a specific class, its list of methods, to a
specific method, all on-the-fly from the keyboard. Right now it spawns off a
separate browser

Sophie