"Boris G. Chr. Shingarov" usib6tfj@pol.ru writes:
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, ...
Yes, imposing some structure onto class comments might be a good idea, for several reasons.
... 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).
An interesting thought. To take the idea further, I think any hyperlinks within an explanation should be bidirectional: we when we are staring at a particular instance, we often want to find not only what it refers to but also who is referring to it.
Implementation note: Attaching unique documentation to each instance would be possible if Squeak had finalizers and weak pointers. An instance being expunged by the garbage collector could, in its finalizer, remove itself and its documentation from a global Explanation dictionary.
On a slight tangent: It seems to me that a documentation browser would be even more important in a prototype-based system, since there would be no class hierarchy to help a user find information. If we think of the entire system as a book, then the documentation browser would be the table of contents.
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).
------------------------------------ Stephen Ma stephen_ma@mindlink.net
Stephen,
Implementation note: Attaching unique documentation to each instance would be possible if Squeak had finalizers and weak pointers. An instance being expunged by the garbage collector could, in its finalizer, remove itself and its documentation from a global Explanation dictionary.
I imagined it a little bit different: the explanation is, in some sense, inside the instance (e.g., Object may have instance variable 'explanation').
On a slight tangent: It seems to me that a documentation browser would be even more important in a prototype-based system, since there would be no class hierarchy to help a user find information.
The key is right here. In a prototype-based system we explicitly regard everything as objects, and want documentation for all objects. But in Smalltalk, what forces us to only put comments on objects which are kinds of Class?
Boris
squeak-dev@lists.squeakfoundation.org
-
Boris G. Chr. Shingarov -
Stephen Ma