Smalltalk › Squeak › Squeak - Dev

Documentation/Comment per package

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

28 messages Options

Nicolas Cellier

Re: Documentation/Comment per package

Chris, these are good arguments.

For who ever used VW refactoring browser, the answer is obvious: if
comment was accessible from class browser, then it would enable
browsing and discovering what is in the image, and it is IMHO
invaluable.

As for small production image, there's not much difference with class
comments, and there should be less package than classes...

Nicolas

2012/7/29 Chris Muller <[hidden email]>:

> On Sun, Jul 29, 2012 at 1:39 PM, Bert Freudenberg <[hidden email]> wrote:
>> Agree with Dale. The normal way to create a new package is by pressing a button in Monticello, not having to write a PackageInfo subclass. Subclassing should only be necessary to override the actual behavior. But storing strings as source code is not changing behavior. Besides, it just feels wrong e.g. having to escape quotes in the string.
>>
>> We do need a better tool for editing packages, agreed. But editing a comment in that tool should not have to
>> generate a method.
>
> Never said that. When I said "the Compiler via the code browser" I
> was not proposing a solution to anything, it was a way of trying to
> ask, "what are your requirements here?".
>
>> Chris, I don't know where you got the idea that subclassing PackageInfo is a good thing, but it surely is not what the vast majority of package authors have been doing.
>> ...The best way to get more package metadata into our packages IMHO is adding these fields to PackageInfo and making a nice tool to edit them.
>> E.g., Monticello's button to add a package could pop open a Package Editor dialog where you fill out the name, license, comment etc. fields for the new package. Straightforward, and even in-the-face.
>
> You keep proposing "solutions" for updating package information but
> never clearly stated the context in which one would want to consume
> that information. Presumably, by the time someone gets to the point
> of dealing with a single MCZ, they're typically already past the point
> of "discovery" about the package and ready to install. Under what
> scenario does someone find a general comment about the package useful
> at this stage?
>
> Unless... you're thinking you to use MC for the discovery
> requirement. But the SM Catalog is more ideal to satisfy the
> "discovery" and "installation" requirements because it's agnostic
> about the underlying package solution being used.
>
> I can describe another scenario. Perhaps someone likes their
> production system to be as small as possible, and so they might prefer
> package verbiage and documentation not forced to be bundled with the
> code, which is all they really want installed in the prod server...
>
>> Compared to that, having to know about making a PackageInfo subclass, thinking where to put it, remembering to override the right methods, that sounds way more obscure, wouldn't you agree? I bet many "normal" developers don't even know what PackageInfo is, and they shouldn't have to.
>
> What else shouldn't a "normal" developer not have to know?
>

Bert Freudenberg

Re: Documentation/Comment per package

In reply to this post by Chris Muller-3

On 29.07.2012, at 14:01, Chris Muller wrote:

So if I understand you correctly, you think adding a comment and license to PackageInfo is not necessary, because you rather want to add that to SqueakMap or some other tool. Fair point. I just don't understand why you were proposing PackageInfo subclasses before. I'm just saying that *if* we want to add package metadata that is versioned by Monticello, then adding that to the PI instance is better than relying on subclassing. Whether we need the whole thing I don't know, we've been living fine without for years, but it sounded like there are people who think it would be a good idea to have it.

>> Compared to that, having to know about making a PackageInfo subclass, thinking where to put it, remembering to override the right methods, that sounds way more obscure, wouldn't you agree? I bet many "normal" developers don't even know what PackageInfo is, and they shouldn't have to.
>
> What else shouldn't a "normal" developer not have to know?

Now you're just teasing ;) There is a huge difference between experts and newbies, but "normal" developers in between these extremes can still be productive. There are many details about the system which less experienced developers do not know about, too many to list really. Or are you constantly thinking about what exactly happens when you press a key or click a mouse button?

- Bert -

David T. Lewis

Re: Documentation/Comment per package

In reply to this post by Bert Freudenberg

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.

Dave

Frank Shearar-3

Re: Documentation/Comment per package

On 30 July 2012 11:35, David T. Lewis <[hidden email]> 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.

frank

> Dave
>
>
>

David T. Lewis

Re: Documentation/Comment per package

On Mon, Jul 30, 2012 at 12:13:52PM +0100, Frank Shearar wrote:

> On 30 July 2012 11:35, David T. Lewis <[hidden email]> 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.

Dave

Chris Muller-3

Re: Documentation/Comment per package

In reply to this post by David T. Lewis

> Subclassing PackageInfo just to add a comment seems wrong, and it is
> certainly not something that I would ever think of doing. Keeping the

My God y'all. I never said the above. Please read my words more
closely and stop putting words in my mouth.

I totally appreciate your point, which is the following:

> 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.

That's fine but it ignores how the information would be used. The
lifecycle of software consumption by Berts "normal" user is:

Discovery ---> Installation ---> Exploration --> Consumption

Discovery and Installation occur from the App Store (SM) -- BEFORE
someone is dealing with a single MCZ to even be ABLE to consume
package meta-data that may be there.

AFTER installation, the user is ready for _deeper_ Exploration, so I
think he's past the point of needing a general package comment.
Actually maybe a general package comment COULD be useful here since
most systems are made up of multiple MCZ packages and that would give
the user a feel for overall package-level responsibilities. Still, my
guess is the user is usually looking to move forward with USING the
software for what it can do, caring less as much about
package-structure and how it works.

And this the stage where I think PackageInfo subclasses can be useful:
The author can *introduce* the package to a newbie user in a way that
is specific to that package. Things that move him *deeper* into the
software like #tutorial, perhaps.

So it's about providing the right information at the right time to
propel the user toward useful Consumption.

I'm not strictly opposed to your proposition, just trying to
understand the scenario in which your MCZ-level Package meta-data is
consumed, but since you won't say, it's hard to be supportive of any
"solutions" yet...

Hannes Hirzel

Re: Documentation/Comment per package

In reply to this post by Bert Freudenberg

On 7/28/12, Bert Freudenberg <[hidden email]> 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?
>
> - Bert -
>

Nice!

Besides clicking on the 'scripts' button to have a look at the comment I can do

PackageInfo allInstances explore

and run a report on the Array I get there.

Are there other places where this package comment shows up or could
easily made to be shown up?

--Hannes

PackageCommentsInMonticelloBrowser.GIF (64K) Download Attachment

Hannes Hirzel

Re: Documentation/Comment per package

In reply to this post by David T. Lewis

On 7/30/12, David T. Lewis <[hidden email]> wrote:

> On Mon, Jul 30, 2012 at 12:13:52PM +0100, Frank Shearar wrote:
>> On 30 July 2012 11:35, David T. Lewis <[hidden email]> 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
>
>
>