"Alan C. Kay" alank@wdi.disney.com writes:
[Tansel Ersavas: graphical class diagrams; screen capture] [Stephen Ma: documentation browser]
I feel very positive and supportive of both suggestions. Our motto is "The system is the curriculum", but we have yet to make good on this, and appreciate very much everyone's interests and contributions in this important area.
Thanks for the encouragement. However, I must warn everyone that I am a complete novice when it comes to Smalltalk -- which is why I know about the need for tutorials! So I may not be the best person to implement the documentation browser.
Actually, I'm not quite that helpless; I've gone through the blue and purple Smalltalk-80 books. If no one else volunteers, I think I can throw together something tolerable in a week or two.
------------------------------------ Stephen Ma stephen_ma@mindlink.net
Stephen,
I guess someone already invented this before me but here is what I think can be of interest:
The code & doc browsers -as well as other tools- should be tightly integrated. Imagine e.g. a new user inspecting some object with the inspector, and the object has an instance variable pointing to an IdentityDictionary. The user selects the IV in the browser and sees 'an IdentityDictionary' in the value pane and now he wonders what could this IdDict mean. I definitely think there must be a tool integrated into each of the other tool, to lead the user to the complete explanation of what IdDict is, - by means of just one mouse click. One approach is to use class comments as what such click can link to, but I guess a prototype(delegation)-based system gives us more field for fantasy, because we can target many of our documentation goals by simply defining a mandatory message #explain, to return an explanation of what this object is, who put it there and for what reason, and how to make profit out of it (it obviously can't be elegantly done in a class- based system).
All: Did anyone see anything similar before? I'm designing a new set of browsers/inspectors/debuggers/workspaces for work with Cheese and am looking for fresh ideas (if the tools will be nothing more than standard Smalltalk tools then they will be not worth implementing - but then Cheese will lack any tools and will be usekess and die).
Boris
Boris G. Chr. Shingarov wrote:
Stephen,
I guess someone already invented this before me but here is what I think can be of interest:
The code & doc browsers -as well as other tools- should be tightly integrated. Imagine e.g. a new user inspecting some object with the inspector, and the object has an instance variable pointing to an IdentityDictionary. The user selects the IV in the browser and sees 'an IdentityDictionary' in the value pane and now he wonders what could this IdDict mean. I definitely think there must be a tool integrated into each of the other tool, to lead the user to the complete explanation of what IdDict is, - by means of just one mouse click. One approach is to use class comments as what such click can link to, but I guess a prototype(delegation)-based system gives us more field for fantasy, because we can target many of our documentation goals by simply defining a mandatory message #explain, to return an explanation of what this object is, who put it there and for what reason, and how to make profit out of it (it obviously can't be elegantly done in a class- based system).
I haven't worked extensively with prototype based systems but I wonder what you mean. It seems like there is a perfectly good implementation for this in class based Smalltalk.
simply define
Object>>explain ^self class explainInstance
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.
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.
All: Did anyone see anything similar before? I'm designing a new set of browsers/inspectors/debuggers/workspaces for work with Cheese and am looking for fresh ideas (if the tools will be nothing more than standard Smalltalk tools then they will be not worth implementing - but then Cheese will lack any tools and will be usekess and die).
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.
Boris
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
squeak-dev@lists.squeakfoundation.org
-
Boris G. Chr. Shingarov -
Dana Anthony -
Stephen Ma