Documentation/Comment per package

Hello,

I wonder if there is a way to describe a certain package. You can put
comments on class side. But what if you want to describe the intent of a
package or the relation of classes inside a package and how to use
them. Is there a way to put information along packages? I was digging
into PackageInfo but dont know how to use/extent it.

TIA
Enno

Create a subclass of PackageInfo for your package.

On Thu, Jul 12, 2012 at 12:58 PM, Enrico Schwass <[hidden email]> wrote:

On 7/15/12, Chris Muller <[hidden email]> wrote:
> Create a subclass of PackageInfo for your package.


PackageInfo subclasses
  gives

 {MCDirtyPackageInfo . MCEmptyPackageInfo . MCMockPackageInfo}

And there seems to be no place of putting a description of the package there.
Am I missing something?

Chris,
Could you please do an example e.g. for Monticello-Base and Monticello-Resitory?

-- Hannes

On 26.07.2012, at 16:26, H. Hirzel wrote:


If having a comment for each package is desirable then we could add it to PackageInfo just like it already supports scripts.

- Bert -

--
best,

On Thu, Jul 26, 2012 at 5:26 PM, Bert Freudenberg <[hidden email]> wrote:

On 26.07.2012, at 16:26, H. Hirzel wrote:

> On 7/15/12, Chris Muller <[hidden email]> wrote:
>> Create a subclass of PackageInfo for your package.
>
>
> PackageInfo subclasses
>  gives
>
> {MCDirtyPackageInfo . MCEmptyPackageInfo . MCMockPackageInfo}
>
> And there seems to be no place of putting a description of the package there.
> Am I missing something?
>
> Chris,
> Could you please do an example e.g. for Monticello-Base and Monticello-Resitory?
>
> -- Hannes

If having a comment for each package is desirable then we could add it to PackageInfo just like it already supports scripts.

+1

 

- Bert -

--
best,

Eliot

But each package may potentially want to have its own subclasses of
PackageInfo for special configuration and/or additional information?

Therefore, we don't need to be adding any state to PackageInfo.



On Thu, Jul 26, 2012 at 7:26 PM, Bert Freudenberg <[hidden email]> wrote:

Chris,

I would think that if you are going to write tools to manipulate the package comment then you'd want to guarantee that there was a place to find/store the comment so extending PackageInfo would seem to be the ticket ...

Dale

----- Original Message -----
| From: "Chris Muller" <[hidden email]>
| To: "The general-purpose Squeak developers list" <[hidden email]>
| Sent: Saturday, July 28, 2012 8:44:42 AM
| Subject: Re: [squeak-dev] Documentation/Comment per package
|
| But each package may potentially want to have its own subclasses of
| PackageInfo for special configuration and/or additional information?
|
| Therefore, we don't need to be adding any state to PackageInfo.
|
|
|
| On Thu, Jul 26, 2012 at 7:26 PM, Bert Freudenberg
| <[hidden email]> wrote:
| >
| > On 26.07.2012, at 16:26, H. Hirzel wrote:
| >
| >> On 7/15/12, Chris Muller <[hidden email]> wrote:
| >>> Create a subclass of PackageInfo for your package.
| >>
| >>
| >> PackageInfo subclasses
| >>  gives
| >>
| >> {MCDirtyPackageInfo . MCEmptyPackageInfo . MCMockPackageInfo}
| >>
| >> And there seems to be no place of putting a description of the
| >> package there.
| >> Am I missing something?
| >>
| >> Chris,
| >> Could you please do an example e.g. for Monticello-Base and
| >> Monticello-Resitory?
| >>
| >> -- Hannes
| >
| >
| > If having a comment for each package is desirable then we could add
| > it to PackageInfo just like it already supports scripts.
| >
| > - Bert -
| >
| >
|
|

Well, I guess I see the Package meta-data (comment, etc.) as part of
the *code* of that package, and so the "tool for manipulating the
package comment" is the Compiler, wielded via a class-browser...

What tool are you talking about?


On Sat, Jul 28, 2012 at 11:10 AM, Dale Henrichs <[hidden email]> wrote:

> Therefore, we don't need to be adding any state to PackageInfo.

Just to clarify - I'm not opposed to adding an inst-var, I just don't
see the need.

Yes, it probably should be a class variable.

As Bert writes earlier in this thread I have to create a subclass of
PackageInfo for my package.
So far it has not actually been used much, only three subclasses. As
Enrico points out this is crucial information to have an entry into
the system.

And the place to put it seems to be a class variable 'description'.
Like in Seaside components.

--Hannes



On 7/28/12, Chris Muller <[hidden email]> 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 -

On 28.07.2012, at 13:39, Bert Freudenberg wrote:

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 -

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

After thinking about it overnight I finally figured out my feeling
about PackageInfo objects:  I'm see them as a blank "canvas" for
authors to have great freedom to describe and introduce their packages
-- even doing multimedia capabilities in some cases.  I think this is
why I'm feeling a natural resistance to imposing a lot of structure
there.  I think some structure is good (like name, comment and
license) but comment alone is not nearly enough and so I think we
should make sure we keep PackageInfo "open" to many more attributes
than just name+comment.

I'm currently "Nay" on what we have in the Inbox because we don't have
a useful and intuitive way to *consume* the comment.  Bert's code is
more for just updating it.  People will not go to "scripts + comment"
just to read package comments.  Until that is addressed, I think the
enhancement in the Inbox does not add value exceeding its weight.

> I'm currently "Nay" on what we have in the Inbox because we don't have
> a useful and intuitive way to *consume* the comment.  Bert's code is
> more for just updating it.  People will not go to "scripts + comment"
> just to read package comments.  Until that is addressed, I think the
> enhancement in the Inbox does not add value exceeding its weight.

Besides that, we already have a place to produce AND consume comments
about packages -- it's called SqueakMap.

Chris,

You have to agree that a `package comment` belongs with the package and should travel where ever the package goes ...

it's still nice to have a place for a package comment in SqueakMap...

Dale

----- Original Message -----
| From: "Chris Muller" <[hidden email]>
| To: "The general-purpose Squeak developers list" <[hidden email]>
| Sent: Sunday, July 29, 2012 9:29:20 AM
| Subject: Re: [squeak-dev] Documentation/Comment per package
|
| > I'm currently "Nay" on what we have in the Inbox because we don't
| > have
| > a useful and intuitive way to *consume* the comment.  Bert's code
| > is
| > more for just updating it.  People will not go to "scripts +
| > comment"
| > just to read package comments.  Until that is addressed, I think
| > the
| > enhancement in the Inbox does not add value exceeding its weight.
|
| Besides that, we already have a place to produce AND consume comments
| about packages -- it's called SqueakMap.
|
|

> You have to agree that a `package comment` belongs with the package and should travel where ever the package goes ...

Yeah that's a good responsibility for a PackageInfo, but until I
understand how it would interplay with IDE tools in a useful way,
simply a message implementation seems enough.

    PackageInfo>>#comment
         ^ String empty

and subclasses can override if they wish.

With this approach you get all the comment versioning / diffing etc.
for "free" vs. Berts approach the comment is a "special" attribute of
the PI that is "hidden" from all of the other attributes such as
#license, #authors, #tutorial, etc.  For THOSE attributes, go to the
PackageInfo class browser and update them, but for the #comment, go
somewhere else because it's stored in a MC definition.

So, it's an inconsistent treatment of PI attributes that I have
trouble understanding why and would not want to try to explain to a
newbie..

Regards,
  Chris

It seems a bit much to require the creation of a subclass of PackageInfo for your project just to supply a package comment ...

I understand your point that without tool support it's kind of a moot point... the tool (whatever and where ever it may be) will probably drive the question of "where to store the comment":

  - do you crack the zip file to get the comment?
  - do you crack the zip file and reify the definitions?
  - something else?

If you have a package comment it would make sense to display the comment on SqueakSource, SqueakMap, in the image, etc....

Dale

----- Original Message -----
| From: "Chris Muller" <[hidden email]>
| To: "Dale Henrichs" <[hidden email]>
| Cc: "The general-purpose Squeak developers list" <[hidden email]>
| Sent: Sunday, July 29, 2012 10:05:20 AM
| Subject: Re: [squeak-dev] Documentation/Comment per package
|
| > You have to agree that a `package comment` belongs with the package
| > and should travel where ever the package goes ...
|
| Yeah that's a good responsibility for a PackageInfo, but until I
| understand how it would interplay with IDE tools in a useful way,
| simply a message implementation seems enough.
|
|     PackageInfo>>#comment
|          ^ String empty
|
| and subclasses can override if they wish.
|
| With this approach you get all the comment versioning / diffing etc.
| for "free" vs. Berts approach the comment is a "special" attribute of
| the PI that is "hidden" from all of the other attributes such as
| #license, #authors, #tutorial, etc.  For THOSE attributes, go to the
| PackageInfo class browser and update them, but for the #comment, go
| somewhere else because it's stored in a MC definition.
|
| So, it's an inconsistent treatment of PI attributes that I have
| trouble understanding why and would not want to try to explain to a
| newbie..
|
| Regards,
|   Chris
|

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. It should just store the comment in the package object. Same goes for other attributes such as license that we agree upon should be declared at a package level.

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.

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.

- Bert -


On 29.07.2012, at 10:33, Dale Henrichs wrote:

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?