[Documentation] What about package comments?

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
20 messages Options
Reply | Threaded
Open this post in threaded view
|

[Documentation] What about package comments?

Hannes Hirzel
Hello

I found the proposal by Bernhard Pieber and Ralph Johnson to introduce
package comments?

It was in the thread HttpView2 where I think some people interested in
documentation will miss it.

An application could be to automatically generate  documentation, i.e.
for example at Squeaksource.

--Hannes

>From the HttpView2 thread

On 4/23/10, Ralph Johnson <[hidden email]> wrote:

> On Fri, Apr 23, 2010 at 5:39 AM, Bernhard Pieber <[hidden email]>wrote:
>
>> - IMHO, there should be first class package comments along the lines of
>> class and method comments, i.e. version controlled in PackageInfo. This
>> would greatly improve the Monticello browser. And SqueakSource could use
>> them as project descriptions. (I once argued [1] that the easiest
>> implementation of this would be a PackageInfo subclass for each package.
>> Its
>> class comment would be the package comment. Pre and post load code could
>> be
>> put there as well. You could reuse all the development tools like that.)
>>
>> [1]
>> http://lists.squeakfoundation.org/pipermail/squeak-dev/2005-February/088181.html
>>
>>
> This seems like a good idea.  What tools would have to change to make this
> work, and could we make this change backwards compatible?  For example, if
> you move the preload and postload code to the PackageInfo subclass then you
> could leave forwarding code behind.  Tools wouldn't bother displaying the
> forwarding code if they saw the PackageInfo subclass, but would keep it so
> that older versions of the tools would still work.
>
> -Ralph
>

Reply | Threaded
Open this post in threaded view
|

Re: [Documentation] What about package comments?

Sean P. DeNigris
Administrator
Hannes Hirzel-2 wrote
I found the proposal by Bernhard Pieber and Ralph Johnson to introduce
package comments?
+100

This seems like an *awesome* idea, but no one commented.  Why the low interest?  It would be great to have a place to summarize the purpose of the package and give starting points into the code e.g. how to start the GUI.

BTW, the original discussion referenced was at http://forum.world.st/SMSqueakMapAdminView-was-Maui-1-2-release-1-td2020021.html#a2047596

I started an issue at http://bugs.squeak.org/view.php?id=7558

Sean
Cheers,
Sean
Reply | Threaded
Open this post in threaded view
|

Re: [Documentation] What about package comments?

Casey Ransberger-2
It's undoubtedly a tasteful idea to include a comment in the metadata for a package. OTOH, I don't think we've really landed on the natural order of what a package "is" yet (see Metacello and Monticello beat-down threads.)
> Why the low
> interest?

I dunno, let's compose an expression that installs everything that we know we can install from squeaksource. Now let's compose an expression that compares the number of classes without class comments to the number of classes with class comments.

Why the low interest?

Maybe you're onto something: maybe the cost of documenting a package is lower than the cost of documenting all of the classes in it...

On Sep 2, 2010, at 7:56 PM, "Sean P. DeNigris" <[hidden email]> wrote:

>
>
> Hannes Hirzel-2 wrote:
>>
>> I found the proposal by Bernhard Pieber and Ralph Johnson to introduce
>> package comments?
>>
> +100
>
> This seems like an *awesome* idea, but no one commented.  Why the low
> interest?  It would be great to have a place to summarize the purpose of the
> package and give starting points into the code e.g. how to start the GUI.
>
> BTW, the original discussion referenced was at
> http://forum.world.st/SMSqueakMapAdminView-was-Maui-1-2-release-1-td2020021.html#a2047596
>
> I started an issue at http://bugs.squeak.org/view.php?id=7558
>
> Sean
> --
> View this message in context: http://forum.world.st/Documentation-What-about-package-comments-tp2062634p2525049.html
> Sent from the Squeak - Dev mailing list archive at Nabble.com.
>

Reply | Threaded
Open this post in threaded view
|

Re: [Documentation] What about package comments?

Hannes Hirzel
Thank you, Sean for bringing up this topic again.

On of the things I have been wondering recently is where the package
actually "lives" in the image. Which objects do  represent packages?
Traditionally a package was just class organization; that means the
class category attached to the class and not an object of it's own.
(This is just out of my head and I would have to check out how things
are these days in the image).

However I think if we are unloading packages for example (which I
happily did last week and beginning of this week see thread
http://lists.squeakfoundation.org/pipermail/squeak-dev/2010-August/152570.html
) it would be a natural step to go find out more about it.

--Hannes

On 9/3/10, Casey Ransberger <[hidden email]> wrote:

> It's undoubtedly a tasteful idea to include a comment in the metadata for a
> package. OTOH, I don't think we've really landed on the natural order of
> what a package "is" yet (see Metacello and Monticello beat-down threads.)
>> Why the low
>> interest?
>
> I dunno, let's compose an expression that installs everything that we know
> we can install from squeaksource. Now let's compose an expression that
> compares the number of classes without class comments to the number of
> classes with class comments.
>
> Why the low interest?
>
> Maybe you're onto something: maybe the cost of documenting a package is
> lower than the cost of documenting all of the classes in it...
>
> On Sep 2, 2010, at 7:56 PM, "Sean P. DeNigris" <[hidden email]>
> wrote:
>
>>
>>
>> Hannes Hirzel-2 wrote:
>>>
>>> I found the proposal by Bernhard Pieber and Ralph Johnson to introduce
>>> package comments?
>>>
>> +100
>>
>> This seems like an *awesome* idea, but no one commented.  Why the low
>> interest?  It would be great to have a place to summarize the purpose of
>> the
>> package and give starting points into the code e.g. how to start the GUI.
>>
>> BTW, the original discussion referenced was at
>> http://forum.world.st/SMSqueakMapAdminView-was-Maui-1-2-release-1-td2020021.html#a2047596
>>
>> I started an issue at http://bugs.squeak.org/view.php?id=7558
>>
>> Sean
>> --
>> View this message in context:
>> http://forum.world.st/Documentation-What-about-package-comments-tp2062634p2525049.html
>> Sent from the Squeak - Dev mailing list archive at Nabble.com.
>>
>
>

Reply | Threaded
Open this post in threaded view
|

Re: [Documentation] What about package comments?

Bert Freudenberg
On 03.09.2010, at 10:28, Hannes Hirzel wrote:

> On of the things I have been wondering recently is where the package actually "lives" in the image.

A package is a (sub-) instance of PackageInfo. Packages are held by PackageOrganizer.

One idea would be to include a PackageInfo subclass in each package, and its class comment or methods would describe the package. That would hook into HelpSystem so one could browse comments, instructions, examples etc. per package.

There are a few conventions for that already, e.g. the class name should end in "Info" and it should be in a category named "PackageName-Info".

- Bert -



Reply | Threaded
Open this post in threaded view
|

Re: [Documentation] What about package comments?

Eliot Miranda-2


On Fri, Sep 3, 2010 at 2:51 AM, Bert Freudenberg <[hidden email]> wrote:
On 03.09.2010, at 10:28, Hannes Hirzel wrote:

> On of the things I have been wondering recently is where the package actually "lives" in the image.

A package is a (sub-) instance of PackageInfo. Packages are held by PackageOrganizer.

One idea would be to include a PackageInfo subclass in each package, and its class comment or methods would describe the package. That would hook into HelpSystem so one could browse comments, instructions, examples etc. per package.

There are a few conventions for that already, e.g. the class name should end in "Info" and it should be in a category named "PackageName-Info".

This is nice.  It's also a place to put package initialization/unloading scripts, etc.  Is there example code for the above conventions anywhere?

cheers
Eliot
 

- Bert -






Reply | Threaded
Open this post in threaded view
|

Re: [Documentation] What about package comments?

Ralph Johnson
In reply to this post by Bert Freudenberg
On 9/3/10, Bert Freudenberg <[hidden email]> wrote:

> A package is a (sub-) instance of PackageInfo. Packages are held by PackageOrganizer.
>
>  One idea would be to include a PackageInfo subclass in each package, and its class comment or methods would describe the package. That would hook into HelpSystem so one could browse comments, instructions, examples etc. per package.
>
>  There are a few conventions for that already, e.g. the class name should end in "Info" and it should be in a category named "PackageName-Info".

We could certainly include a PackageInfo subclass in a package.  But
Monticello wouldn't use it to make the instance of the package, would
it?

How should tools change to use this convention?  We could make a few
test cases (i.e. packages that contain a class like this) and then the
tool makers could use them to change their tools.

-Ralph

Reply | Threaded
Open this post in threaded view
|

Re: [Documentation] What about package comments?

Sean P. DeNigris
Administrator
In reply to this post by Bert Freudenberg
Bert Freudenberg wrote
On 03.09.2010, at 10:28, Hannes Hirzel wrote:
One idea would be to include a PackageInfo subclass in each package, and its class comment or methods would describe the package. That would hook into HelpSystem so one could browse comments, instructions, examples etc. per package.
I was playing around in HelpSystem.  What would be the advantage of custom PackageInfo classes vs. putting whatever info you're talking about in a CustomHelp subclass?  Are you talking about adding a standard API to PackageInfo to be overridden in the subclasses, e.g. PackageInfo>>license = #MIT, like Steph's DrDoc project?

Sean
Cheers,
Sean
bpi
Reply | Threaded
Open this post in threaded view
|

Re: [Documentation] What about package comments?

bpi
In reply to this post by Ralph Johnson
Am 03.09.2010 um 19:59 schrieb Ralph Johnson:
> On 9/3/10, Bert Freudenberg <[hidden email]> wrote:
>> A package is a (sub-) instance of PackageInfo. Packages are held by PackageOrganizer.
>>
>> One idea would be to include a PackageInfo subclass in each package, and its class comment or methods would describe the package. That would hook into HelpSystem so one could browse comments, instructions, examples etc. per package.
>>
>> There are a few conventions for that already, e.g. the class name should end in "Info" and it should be in a category named "PackageName-Info".
> We could certainly include a PackageInfo subclass in a package.  But
> Monticello wouldn't use it to make the instance of the package, would
> it?
The strange thing is that PackageInfo supported subclasses from day one. According to Avi they were even required at first. However, I looked but could not find a place in the code where they are instantiated. It seems that one has to manually register them by code in order to use them. It seems that no PackageInfo subclasses can be created by just using the tools. :-/

- Bernhard
Reply | Threaded
Open this post in threaded view
|

Re: [Documentation] What about package comments?

Andreas.Raab
On 9/3/2010 3:08 PM, Bernhard Pieber wrote:

> Am 03.09.2010 um 19:59 schrieb Ralph Johnson:
>> On 9/3/10, Bert Freudenberg<[hidden email]>  wrote:
>>> A package is a (sub-) instance of PackageInfo. Packages are held by PackageOrganizer.
>>>
>>> One idea would be to include a PackageInfo subclass in each package, and its class comment or methods would describe the package. That would hook into HelpSystem so one could browse comments, instructions, examples etc. per package.
>>>
>>> There are a few conventions for that already, e.g. the class name should end in "Info" and it should be in a category named "PackageName-Info".
>> We could certainly include a PackageInfo subclass in a package.  But
>> Monticello wouldn't use it to make the instance of the package, would
>> it?
> The strange thing is that PackageInfo supported subclasses from day one. According to Avi they were even required at first. However, I looked but could not find a place in the code where they are instantiated. It seems that one has to manually register them by code in order to use them. It seems that no PackageInfo subclasses can be created by just using the tools. :-/

If you explore "PackageOrganizer default packages" in 4.1 you will find
that there is (for example) AnObsoleteFlexibleVocabulariesInfo. Which
illustrates my dislike of PI subclassing very well :-)

Cheers,
   - Andreas

Reply | Threaded
Open this post in threaded view
|

Re: [Documentation] What about package comments?

Hannes Hirzel
In reply to this post by Bert Freudenberg
Bert, thank you for the additional clues you provide go further into this.

On 9/3/10, Bert Freudenberg <[hidden email]> wrote:

> On 03.09.2010, at 10:28, Hannes Hirzel wrote:
>
>> On of the things I have been wondering recently is where the package
>> actually "lives" in the image.
>
> A package is a (sub-) instance of PackageInfo. Packages are held by
> PackageOrganizer.
>
> One idea would be to include a PackageInfo subclass in each package, and its
> class comment or methods would describe the package. That would hook into
> HelpSystem so one could browse comments, instructions, examples etc. per
> package.

I like this idea.


> There are a few conventions for that already, e.g. the class name should end
> in "Info" and it should be in a category named "PackageName-Info".

There are some questions, see below.

>
> - Bert -
>



I found the package 'PackageInfo'.

It contains four classes
PackageInfo allInstances size 29
PackageList allInstances size   0
PackageOrganizer allInstances size   1
PackageServices allInstances size  0

Note:
I am using an image I had run through the process of
SmalltalkImage current unloadAllKnownPackages
(details see http://lists.squeakfoundation.org/pipermail/squeak-dev/2010-August/153026.html)
I get the 10MB current "minimal" Squeak 4.1 trunk image.


I get
PackagePaneBrowser new packageList size  24
and
PackagePaneBrowser new packageList
is

#('Kernel' 'Collections' 'Exceptions' 'Files' 'Balloon' 'Graphics'
'Morphic' 'Multilingual' 'Network' 'PackageInfo' 'SUnit' 'Sound'
'Compiler' 'Compression' 'System' 'Tools' 'Monticello'
'MonticelloConfigurations' 'ToolBuilder' 'MorphicExtras' 'TrueType'
'ShoutCore' 'HelpSystem' 'Help')

My questions

1) How are the 29 PackageInfo instances currently used? How have they
been created?
2) What does the PackageOrganizer instance do? Is it just used by the
PackagePaneBrowser?
3) There is no instance variable 'description' or 'comment' in the
class #PackageInfo ***
4) What should we do next? Are there objections going ahead creating
subclasses of PackageInfo and put them into the packages.
5) Which are the references to earlier discussions of this?

--Hannes



***
Object subclass: #PackageInfo
        instanceVariableNames: 'packageName methodCategoryPrefix preamble
postscript preambleOfRemoval postscriptOfRemoval'
        classVariableNames: ''
        poolDictionaries: ''
        category: 'PackageInfo-Base'

Reply | Threaded
Open this post in threaded view
|

Re: [Documentation] What about package comments?

Hannes Hirzel
In reply to this post by Andreas.Raab
On 9/4/10, Andreas Raab <[hidden email]> wrote:

> On 9/3/2010 3:08 PM, Bernhard Pieber wrote:
>> Am 03.09.2010 um 19:59 schrieb Ralph Johnson:
>>> On 9/3/10, Bert Freudenberg<[hidden email]>  wrote:
>>>> A package is a (sub-) instance of PackageInfo. Packages are held by
>>>> PackageOrganizer.
>>>>
>>>> One idea would be to include a PackageInfo subclass in each package, and
>>>> its class comment or methods would describe the package. That would hook
>>>> into HelpSystem so one could browse comments, instructions, examples
>>>> etc. per package.
>>>>
>>>> There are a few conventions for that already, e.g. the class name should
>>>> end in "Info" and it should be in a category named "PackageName-Info".
>>> We could certainly include a PackageInfo subclass in a package.  But
>>> Monticello wouldn't use it to make the instance of the package, would
>>> it?
>> The strange thing is that PackageInfo supported subclasses from day one.
>> According to Avi they were even required at first. However, I looked but
>> could not find a place in the code where they are instantiated. It seems
>> that one has to manually register them by code in order to use them. It
>> seems that no PackageInfo subclasses can be created by just using the
>> tools. :-/
>
> If you explore "PackageOrganizer default packages" in 4.1 you will find
> that there is (for example) AnObsoleteFlexibleVocabulariesInfo. Which
> illustrates my dislike of PI subclassing very well :-)
>
> Cheers,
>    - Andreas
>
>

Andreas,
In the minimal image I use (
http://lists.squeakfoundation.org/pipermail/squeak-dev/2010-August/153026.html
) I do not find AnObsoleteFlexibleVocabulariesInfo anymore. So this
looks just like a bug.

Could you please elaborate why you do not like to subclass PackageInfo?

What is your proposal? Where should we put package descriptions, usage
instructions, example code snippets?

Cheers
--Hannes

Reply | Threaded
Open this post in threaded view
|

Re: [Documentation] What about package comments?

Hannes Hirzel
P.S.

Sean started a thread on the Pharo list
   "Package comments"
I

Reply | Threaded
Open this post in threaded view
|

Re: [Documentation] What about package comments?

Bert Freudenberg
In reply to this post by Hannes Hirzel
On 04.09.2010, at 07:53, Hannes Hirzel wrote:

> 1) How are the 29 PackageInfo instances currently used?

To gather info about which classes and methods are in a Monticello package. Also, to hold package load/unload scripts (which is a hack).

> How have they been created?

Typically by MCPackage>>packageInfo.

Or interactively. E.g. one can ask for all ToolBuilder classes even though ToolBuilder is 4 separate MC packages in trunk:

        (PackageInfo named: 'ToolBuilder') classes

> 2) What does the PackageOrganizer instance do?

It holds onto PackageInfo instances, so that after creating one you always get the same instance.

> Is it just used by the PackagePaneBrowser?

The PackagePaneBrowser has nothing to do with packages. It operates on class categories, not packages. I do not find it useful.

The only shipping browser showing packages is in Monticello, when you click "browse". Monticello has a separate registry:

        MCWorkingCopy allManagers collect: #package

- Bert -


Reply | Threaded
Open this post in threaded view
|

Re: [Documentation] What about package comments?

Chris Muller-3
In reply to this post by bpi
I have been creating PackageInfo subclasses for years for all of my
packages.  I really like storing meta information about packages
within the package itself and I recommend that others do this too,
because it allows the system more easily reflect on itself.

I use PackageInfo subclasses to sort packages in load-dependent order
and to easily create SAR files with "one-click."  (See MaSarPackage,
on SqueakMap).

MaSarPackage includes an extension to PackageInfo that allows proper
registration of a PackageInfo subclass, but to default to a superclass
instance if non-existent.  I think we should consider adopting this
into the trunk so that any package that wants to can declare its own
meta information and have it be saved in with the MC package.

 - Chris

On Fri, Sep 3, 2010 at 5:08 PM, Bernhard Pieber <[hidden email]> wrote:

> Am 03.09.2010 um 19:59 schrieb Ralph Johnson:
>> On 9/3/10, Bert Freudenberg <[hidden email]> wrote:
>>> A package is a (sub-) instance of PackageInfo. Packages are held by PackageOrganizer.
>>>
>>> One idea would be to include a PackageInfo subclass in each package, and its class comment or methods would describe the package. That would hook into HelpSystem so one could browse comments, instructions, examples etc. per package.
>>>
>>> There are a few conventions for that already, e.g. the class name should end in "Info" and it should be in a category named "PackageName-Info".
>> We could certainly include a PackageInfo subclass in a package.  But
>> Monticello wouldn't use it to make the instance of the package, would
>> it?
> The strange thing is that PackageInfo supported subclasses from day one. According to Avi they were even required at first. However, I looked but could not find a place in the code where they are instantiated. It seems that one has to manually register them by code in order to use them. It seems that no PackageInfo subclasses can be created by just using the tools. :-/
>
> - Bernhard
>

Reply | Threaded
Open this post in threaded view
|

Re: [Documentation] What about package comments?

Hannes Hirzel
Chris, could you please elaborate with code snippets how you have been
creating PackageInfo subclasses?


I assume you added some instance variables in the subclasses.

BTW the instance variables of PackageInfo are not commented. What are they for?

I have opened a ticket for
    PackageInfo class comment

http://bugs.squeak.org/view.php?id=7562

where I put some of the discussion here.

The goal is to have some instructions how to use PackageInfo.

--Hannes


On 9/6/10, Chris Muller <[hidden email]> wrote:

> I have been creating PackageInfo subclasses for years for all of my
> packages.  I really like storing meta information about packages
> within the package itself and I recommend that others do this too,
> because it allows the system more easily reflect on itself.
>
> I use PackageInfo subclasses to sort packages in load-dependent order
> and to easily create SAR files with "one-click."  (See MaSarPackage,
> on SqueakMap).
>
> MaSarPackage includes an extension to PackageInfo that allows proper
> registration of a PackageInfo subclass, but to default to a superclass
> instance if non-existent.  I think we should consider adopting this
> into the trunk so that any package that wants to can declare its own
> meta information and have it be saved in with the MC package.
>
>  - Chris
>
> On Fri, Sep 3, 2010 at 5:08 PM, Bernhard Pieber <[hidden email]> wrote:
>> Am 03.09.2010 um 19:59 schrieb Ralph Johnson:
>>> On 9/3/10, Bert Freudenberg <[hidden email]> wrote:
>>>> A package is a (sub-) instance of PackageInfo. Packages are held by
>>>> PackageOrganizer.
>>>>
>>>> One idea would be to include a PackageInfo subclass in each package, and
>>>> its class comment or methods would describe the package. That would hook
>>>> into HelpSystem so one could browse comments, instructions, examples
>>>> etc. per package.
>>>>
>>>> There are a few conventions for that already, e.g. the class name should
>>>> end in "Info" and it should be in a category named "PackageName-Info".
>>> We could certainly include a PackageInfo subclass in a package.  But
>>> Monticello wouldn't use it to make the instance of the package, would
>>> it?
>> The strange thing is that PackageInfo supported subclasses from day one.
>> According to Avi they were even required at first. However, I looked but
>> could not find a place in the code where they are instantiated. It seems
>> that one has to manually register them by code in order to use them. It
>> seems that no PackageInfo subclasses can be created by just using the
>> tools. :-/
>>
>> - Bernhard
>>
>
>

Reply | Threaded
Open this post in threaded view
|

Re: [Documentation] What about package comments?

Chris Muller-4
PackageInfo subclasses do not add any extra inst-vars, and they
shouldn't because the primary method of persistence, Monticello, does
not persist objects, only code.  That code can be run at various times
to assist with configuration.  They only override certain methods that
declare the structure and contents of the package.

Creating a PackageInfo subclass is no different than creating a
subclass of any other class:

PackageInfo subclass: #MyPackageInfo
        instanceVariableNames: ''
        classVariableNames: ''
        poolDictionaries: ''
        category: 'MyPackage-Info'

For example, if a package requires several system changes (like
Stephane Rollandin's muO), then one could override #patchNames to,
instead of answering an empty Array, answer an Array of strings which
are the names of the change-set files, in order, that should be loaded
to make a running muO system.

Similarly, the MyPackageInfo subclass can also report its *immediate*
dependencies in terms of other packages by overriding
#prerequisitePackageNames:

prerequisitePackageNames
        ^ super prerequisitePackageNames ,
                { MyPrerequisitePackageInfo packageName.
                MyOtherPrerequisitePackageInfo packageName }

Even by only declaring immediate dependencies of each package, the
full dependency tree can then be calculated in load-dependent order by
the computer..

Personally, what I like about PackageInfo is that it is very open and
lightweight.  *I* added the notion of #prerequisitePackageNames to
handle the dependencies myself.  But if this is of general interest we
should fold it into the trunk.

This and more documentation is available on the wiki:

    http://wiki.squeak.org/squeak/3329
    http://wiki.squeak.org/squeak/6155

 - Chris


On Wed, Sep 8, 2010 at 6:10 AM, Hannes Hirzel <[hidden email]> wrote:

> Chris, could you please elaborate with code snippets how you have been
> creating PackageInfo subclasses?
>
>
> I assume you added some instance variables in the subclasses.
>
> BTW the instance variables of PackageInfo are not commented. What are they for?
>
> I have opened a ticket for
>    PackageInfo class comment
>
> http://bugs.squeak.org/view.php?id=7562
>
> where I put some of the discussion here.
>
> The goal is to have some instructions how to use PackageInfo.
>
> --Hannes
>
>
> On 9/6/10, Chris Muller <[hidden email]> wrote:
>> I have been creating PackageInfo subclasses for years for all of my
>> packages.  I really like storing meta information about packages
>> within the package itself and I recommend that others do this too,
>> because it allows the system more easily reflect on itself.
>>
>> I use PackageInfo subclasses to sort packages in load-dependent order
>> and to easily create SAR files with "one-click."  (See MaSarPackage,
>> on SqueakMap).
>>
>> MaSarPackage includes an extension to PackageInfo that allows proper
>> registration of a PackageInfo subclass, but to default to a superclass
>> instance if non-existent.  I think we should consider adopting this
>> into the trunk so that any package that wants to can declare its own
>> meta information and have it be saved in with the MC package.
>>
>>  - Chris
>>
>> On Fri, Sep 3, 2010 at 5:08 PM, Bernhard Pieber <[hidden email]> wrote:
>>> Am 03.09.2010 um 19:59 schrieb Ralph Johnson:
>>>> On 9/3/10, Bert Freudenberg <[hidden email]> wrote:
>>>>> A package is a (sub-) instance of PackageInfo. Packages are held by
>>>>> PackageOrganizer.
>>>>>
>>>>> One idea would be to include a PackageInfo subclass in each package, and
>>>>> its class comment or methods would describe the package. That would hook
>>>>> into HelpSystem so one could browse comments, instructions, examples
>>>>> etc. per package.
>>>>>
>>>>> There are a few conventions for that already, e.g. the class name should
>>>>> end in "Info" and it should be in a category named "PackageName-Info".
>>>> We could certainly include a PackageInfo subclass in a package.  But
>>>> Monticello wouldn't use it to make the instance of the package, would
>>>> it?
>>> The strange thing is that PackageInfo supported subclasses from day one.
>>> According to Avi they were even required at first. However, I looked but
>>> could not find a place in the code where they are instantiated. It seems
>>> that one has to manually register them by code in order to use them. It
>>> seems that no PackageInfo subclasses can be created by just using the
>>> tools. :-/
>>>
>>> - Bernhard
>>>
>>
>>
>

Reply | Threaded
Open this post in threaded view
|

Re: [Documentation] What about package comments?

Chris Muller-4
I wrote:

> Personally, what I like about PackageInfo is that it is very open and
> lightweight.

.. AND, that it is already part of core Squeak, and SCM tool agnostic...


> On Wed, Sep 8, 2010 at 6:10 AM, Hannes Hirzel <[hidden email]> wrote:
>> Chris, could you please elaborate with code snippets how you have been
>> creating PackageInfo subclasses?
>>
>>
>> I assume you added some instance variables in the subclasses.
>>
>> BTW the instance variables of PackageInfo are not commented. What are they for?
>>
>> I have opened a ticket for
>>    PackageInfo class comment
>>
>> http://bugs.squeak.org/view.php?id=7562
>>
>> where I put some of the discussion here.
>>
>> The goal is to have some instructions how to use PackageInfo.
>>
>> --Hannes
>>
>>
>> On 9/6/10, Chris Muller <[hidden email]> wrote:
>>> I have been creating PackageInfo subclasses for years for all of my
>>> packages.  I really like storing meta information about packages
>>> within the package itself and I recommend that others do this too,
>>> because it allows the system more easily reflect on itself.
>>>
>>> I use PackageInfo subclasses to sort packages in load-dependent order
>>> and to easily create SAR files with "one-click."  (See MaSarPackage,
>>> on SqueakMap).
>>>
>>> MaSarPackage includes an extension to PackageInfo that allows proper
>>> registration of a PackageInfo subclass, but to default to a superclass
>>> instance if non-existent.  I think we should consider adopting this
>>> into the trunk so that any package that wants to can declare its own
>>> meta information and have it be saved in with the MC package.
>>>
>>>  - Chris
>>>
>>> On Fri, Sep 3, 2010 at 5:08 PM, Bernhard Pieber <[hidden email]> wrote:
>>>> Am 03.09.2010 um 19:59 schrieb Ralph Johnson:
>>>>> On 9/3/10, Bert Freudenberg <[hidden email]> wrote:
>>>>>> A package is a (sub-) instance of PackageInfo. Packages are held by
>>>>>> PackageOrganizer.
>>>>>>
>>>>>> One idea would be to include a PackageInfo subclass in each package, and
>>>>>> its class comment or methods would describe the package. That would hook
>>>>>> into HelpSystem so one could browse comments, instructions, examples
>>>>>> etc. per package.
>>>>>>
>>>>>> There are a few conventions for that already, e.g. the class name should
>>>>>> end in "Info" and it should be in a category named "PackageName-Info".
>>>>> We could certainly include a PackageInfo subclass in a package.  But
>>>>> Monticello wouldn't use it to make the instance of the package, would
>>>>> it?
>>>> The strange thing is that PackageInfo supported subclasses from day one.
>>>> According to Avi they were even required at first. However, I looked but
>>>> could not find a place in the code where they are instantiated. It seems
>>>> that one has to manually register them by code in order to use them. It
>>>> seems that no PackageInfo subclasses can be created by just using the
>>>> tools. :-/
>>>>
>>>> - Bernhard
>>>>
>>>
>>>
>>
>

Reply | Threaded
Open this post in threaded view
|

Re: [Documentation] What about package comments?

Hannes Hirzel
Hello Chris

I read your answer and found out that to come from MCWorkingCopy to
PackageInfo I need to do the following

MCWorkingCopy
"is a subclass of MCPackageManager"

MCWorkingCopy allManagers collect: #package.
"gives an array of MCPackage"

MCPackage>>packageInfo
gives a PackageInfo instance

Here comes my follow-up question?
How do I get from a PackageInfo instance to the MCWorkingCopy instance?
I do get a PackageInfo instance for example with
    PackageInfo named: 'MyPackage'

If we can do this we can get to the version info and display it in the
browser we get with
    PackageList open


--Hannes



On 9/8/10, Chris Muller <[hidden email]> wrote:

> I wrote:
>
>> Personally, what I like about PackageInfo is that it is very open and
>> lightweight.
>
> .. AND, that it is already part of core Squeak, and SCM tool agnostic...
>
>
>> On Wed, Sep 8, 2010 at 6:10 AM, Hannes Hirzel <[hidden email]>
>> wrote:
>>> Chris, could you please elaborate with code snippets how you have been
>>> creating PackageInfo subclasses?
>>>
>>>
>>> I assume you added some instance variables in the subclasses.
>>>
>>> BTW the instance variables of PackageInfo are not commented. What are
>>> they for?
>>>
>>> I have opened a ticket for
>>>    PackageInfo class comment
>>>
>>> http://bugs.squeak.org/view.php?id=7562
>>>
>>> where I put some of the discussion here.
>>>
>>> The goal is to have some instructions how to use PackageInfo.
>>>
>>> --Hannes
>>>
>>>
>>> On 9/6/10, Chris Muller <[hidden email]> wrote:
>>>> I have been creating PackageInfo subclasses for years for all of my
>>>> packages.  I really like storing meta information about packages
>>>> within the package itself and I recommend that others do this too,
>>>> because it allows the system more easily reflect on itself.
>>>>
>>>> I use PackageInfo subclasses to sort packages in load-dependent order
>>>> and to easily create SAR files with "one-click."  (See MaSarPackage,
>>>> on SqueakMap).
>>>>
>>>> MaSarPackage includes an extension to PackageInfo that allows proper
>>>> registration of a PackageInfo subclass, but to default to a superclass
>>>> instance if non-existent.  I think we should consider adopting this
>>>> into the trunk so that any package that wants to can declare its own
>>>> meta information and have it be saved in with the MC package.
>>>>
>>>>  - Chris
>>>>
>>>> On Fri, Sep 3, 2010 at 5:08 PM, Bernhard Pieber <[hidden email]>
>>>> wrote:
>>>>> Am 03.09.2010 um 19:59 schrieb Ralph Johnson:
>>>>>> On 9/3/10, Bert Freudenberg <[hidden email]> wrote:
>>>>>>> A package is a (sub-) instance of PackageInfo. Packages are held by
>>>>>>> PackageOrganizer.
>>>>>>>
>>>>>>> One idea would be to include a PackageInfo subclass in each package,
>>>>>>> and
>>>>>>> its class comment or methods would describe the package. That would
>>>>>>> hook
>>>>>>> into HelpSystem so one could browse comments, instructions, examples
>>>>>>> etc. per package.
>>>>>>>
>>>>>>> There are a few conventions for that already, e.g. the class name
>>>>>>> should
>>>>>>> end in "Info" and it should be in a category named
>>>>>>> "PackageName-Info".
>>>>>> We could certainly include a PackageInfo subclass in a package.  But
>>>>>> Monticello wouldn't use it to make the instance of the package, would
>>>>>> it?
>>>>> The strange thing is that PackageInfo supported subclasses from day
>>>>> one.
>>>>> According to Avi they were even required at first. However, I looked
>>>>> but
>>>>> could not find a place in the code where they are instantiated. It
>>>>> seems
>>>>> that one has to manually register them by code in order to use them. It
>>>>> seems that no PackageInfo subclasses can be created by just using the
>>>>> tools. :-/
>>>>>
>>>>> - Bernhard
>>>>>
>>>>
>>>>
>>>
>>
>

Reply | Threaded
Open this post in threaded view
|

Re: [Documentation] What about package comments?

Bert Freudenberg

On 13.09.2010, at 00:24, Hannes Hirzel wrote:

> How do I get from a PackageInfo instance to the MCWorkingCopy instance?

(MCPackage named: 'MyPackage') workingCopy

- Bert -