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