I thought it might be useful to answer this on a general level.
I'd say documentation is particularly useful for parts that are not already
documented (particularly, in the Smalltalk-80 book[s], or the squeakbook),
either because they are new or have been changed since then. Also, that the
more "core" the functionality is, and the less likely the code is to change
fundamentally, the more useful documentation would be. (Perhaps this is
obvious and everyone agrees on it?)
Now what would this mean? Morphic is certainly a central new part, but there
are already (too) many different pieces on that.
I'd suggest the whole image segments/SmartFileStream/project loading complex
of various classes. (If not all, then any part of it would be nice.)
This because it could be very useful as a foundation for general modularity
mechanisms, but if they are to serve such a central function, then they
dearly need to be well documented. Just such a small part of this as
veryDeepCopy needs to be better documented. I have learned that part myself
but that was in the hard way. The part where GC is used to map out a part of
memory would be nice to have clearly explained as well. One shouldn't have
to understand the GC implementation to use that mechanism.
Morphic's Redraw Mechanisms
Henrik also suggests:
One piece of Morphic that is not yet documented is the drawing cycle. It is
also not exactly intuitive, it can be really hard to debug. It would be very
nice to have good diagrams and so on that explain double buffering and how
redrawing is triggered and when it is carried out, etc..
Jim Benson suggests:
I'd love to see a high level abstract overview of how the eToys system is
put together, and how that effects the more concrete implementation. For
example, some of the things sprinkled throughout the image are references to
playfields, flaps, players, and scripts. AFAIK there is no single document
that gives the overview of what these terms mean, how they are related, and,
more concretely, how those concepts show up in the image.
While this is a rapidly changing area of Squeak, the concepts are pretty
well in place and it would be nice to see a short "white paper" of eToys. I
know it would have saved me a lot of time a couple of years ago.
Richard O'Keefe suggests writing up how ParagraphEditor and its relatives work.
Low-Level OS Interfaces
Vincent Coetzee suggests:
I have recently been doing some work around using Squeak to produce
native Cocoa apps on Mac OS X. Documentation regarding the mechanism
used to channel OS events into Squeak and how the event handling is
performed in Squeak might be very useful. Is this covered in one of the
Smalltalk books, or does Squeak use significantly different mechanisms
for handling this ?
Be sure, guys, that you check what already exists before dipping into this – there is an chapter on some of this stuff in the upcoming Squeak book editted by Mark Guzdial and Kim Rose.
I think the EventRecorderMorph in squeak could be used for a pretty simple walkthrough. I think this would be easiest to do. I think it's supposed to have a compressed audio stream too, but i couldn't seem to find that. It would really be great if a guru would just spend an hour or two making EventRecorder tapes for the newcomers.
For those interested I've created a little Tutorial on Multi-threaded Squeak. Hope this is helpful to someone.
Link to this Page
- Extra Credit last edited on 22 June 2007 at 12:22 pm by balladeer.cc.gatech.edu