Documenting Squeak

Stephen Ma stephen_ma at mindlink.bc.ca
Tue Mar 31 15:17:17 UTC 1998


"Boris G. Chr. Shingarov" <usib6tfj at 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 at mindlink.net>





More information about the Squeak-dev mailing list