Dana,

> And in the superclass for classes (Behavior, I think)
> define explainInstance to return "instance of", the class comment;
> also define Behavior>explain to return "class of", the class comment.

I hardly see what this buys you as to _documentation_ (vs. productivity
in its use) - while it does save the user several mouse clicks to
access the existing documentation/comment, it does not add to the
documentation itself. (please correct me if I'm wrong)

> This gives you an acceptable, class comment based system,
> which can easily be overriden and extended either at the
> class or instance level.  Just define the class method
> explainInstance to change instance explanation behavior
> that's the same for every instance; define the instance
> method explain for instance explanations that vary by
> the instance; and override the class method explain to
> change the explanation of the class object itself.

Yes - and the problem is right here: you want instance
explanations to vary by the instance, which means implement
different behavior on #explain in each instance, i.e. do
something typical for a prototyped system.

> VisualWorks has an explain feature but it does'nt work exactly
> this way, I dont' really know how it works, but it might be
> similar.

This is not what I try to achieve.  In the example in my
previous posting, I didn't mean to explain to the user what
an IdentityDictionary is.  This is already documented in the
class comment (and other IdentityDictionary-related places),
so providing an easy link to those places is not really significant.
What I was trying to show to the user was, why the variable
pointed to this IdDict, and why the IdDict really should be
like what it's now - i.e., an explanation of the use if the ID
_in this current context_.  In other words, I want to clarify
not on the ID but on the code which uses it...

Boris