reference manual need

Andrew P. Black black at cse.ogi.edu
Mon May 21 06:12:06 UTC 2001


Dear Rosemary,

At 18:57 -0400 2001.05.20, Rosemary Michelle Simpson wrote:

>
>As a consequence of the very helpful responses I've gotten today,
>I've formed the following tentative initial goals for this work:
>
>* an online extensible, easily modifiable encyclopedia of Squeak
>classes

You will notice, if you haven't already, that most of the material in 
the "Classes Reference" is extracted directly from the method 
comments in the code.  Andrew Greenberg did this, and I'm not sure 
what tools he used (Andrew?).

Much of my contribution was to shorten, correct and re-phrase these 
comments, in order to make them more correct and more intelligible. 
The problem with what I did is that these improved comments have not 
found their way back into the source code.

So my suggestion is that whatever work you do, Rosemary, you ensure 
that there is only one form that gets edited and that all the rest 
are generated from it.   Note that there is already a preference in 
Squeak that lets you look at the method comments without looking at 
the code.  (In general preferences select "optionalButtons", and in 
browsing preferences select "sourceCommentToggleInBrowsers")

One of the difficulties with editing the source to improve the 
comments is that I get the feeling (maybe incorrectly) that Squeak 
Central will not welcome an enormous change set that does nothing but 
change the method comments or add class comments.  I wonder if this 
would be helped by changing the fileout format (and the browser?) so 
that comments and code are separated, and, for example, comments 
could be changed without recompiling the code?

	Andrew







More information about the Squeak-dev mailing list