[squeak-dev] Documentation/Comment per package

H. Hirzel hannes.hirzel at gmail.com
Mon Jul 30 18:37:55 UTC 2012


On 7/30/12, David T. Lewis <lewis at mail.msen.com> wrote:
> On Mon, Jul 30, 2012 at 12:13:52PM +0100, Frank Shearar wrote:
>> On 30 July 2012 11:35, David T. Lewis <lewis at mail.msen.com> wrote:
>> > On Sat, Jul 28, 2012 at 02:33:59PM -0700, Bert Freudenberg wrote:
>> >> On 28.07.2012, at 13:39, Bert Freudenberg wrote:
>> >>
>> >> > Guys, please take a step back. There is no "code".
>> >> >
>> >> > Q: The comment of a class is held where?
>> >> > A: An instance variable of the class object.
>> >> >
>> >> > Q: The comment of a package should be held where?
>> >> > A: An instance variable of the package object.
>> >> >
>> >> > Everything else is just a tools issue. If we had a browser for
>> >> > packages, it would allow editing the package comment.
>> >> >
>> >> > Right now the browser to edit packages is Monticello. And it would
>> >> > work just like editing the preambles and postscripts of a package.
>> >> > It's a trivial addition really. As far as Monticello is concerned, it
>> >> > would just be another kind of definition.
>> >> >
>> >> > Guess I should just code it up ...
>> >> >
>> >> > - Bert -
>> >>
>> >> Done. Very straight-forward. Take a peek in the inbox,
>> >> PackageInfo-Base-bf.65 and Monticello-bf.513.
>> >>
>> >> You need to press the "Scripts" button in MC to edit the comment. We
>> >> can decide on a better label later.
>> >>
>> >> Yay/nay?
>> >>
>> >
>> > Yay from me.
>> >
>> > Subclassing PackageInfo just to add a comment seems wrong, and it is
>> > certainly not something that I would ever think of doing. Keeping the
>> > package comments on SqueakMap does not seem right. Bert's explanation
>> > and implementation make sense to me, so +1.
>>
>> In other words you feel that the sort of information that goes in a
>> package's comment is not the sort of information that goes in
>> SqueakMap? That sounds sensible: the SM description for Control (to
>> use an arbitrary example) would say "Control provides mechanisms for
>> creating, composing and calculating with delimited continuations". In
>> other words, what it's for, why you should care, and so on. Its
>> PackageInfo comment would explain the basic architecture,
>> implementation strategies, and the like.
>>
>
> All I'm saying is that I agree with Bert's assessment exactly as he stated
> it above. If a package has a comment, then the comment should be held by
> the package object, in the same way that the comment for a class is held
> by the class object. The implementation should follow from that basic
> design consideration.

+1

> Dave
>
>
>


More information about the Squeak-dev mailing list