At the moment we need to put the package comment in a particular class
of the package.

A reminder: Squeak does not support package comments, a long standing issue.

For an earlier 'package comment' discussion see for example
   http://forum.world.st/Documentation-What-about-package-comments-td2062634.html

More challenging than the question where to put the package comments
is actually getting them in the first place.

So I'd say let's not get sidetracked in this thread and focus on
describing the Monticello package design. So that we can put it into
one of the major classes and refer to it from the other important
classes.

Karl, if you look at the Monticello classes what questions do you have?


--Hannes

On 1/22/13, karl ramberg <karlramberg at gmail.com> wrote:
> Maybe we should have a package comment that describe how the whole
> structure is so it's easier to
> get hunch of where to start looking for a certain functionality.
>
> Karl
>
>
>
>
> On Tue, Jan 22, 2013 at 10:23 AM, Nicolas Cellier <
> nicolas.cellier.aka.nice at gmail.com> wrote:
>
>> IMO, the fact that code is crystal clear is not a good reason to omit
>> documentation.
>> There is also an effect of volume.
>> The fact that MC is huge makes it impossible to embrass its overall
>> structure for a newcomer.
>>
>> Often in Smalltalk, we pick up a very small detail, like this case of
>> cleaning a cache, and have to reconstruct a mental image of MC
>> architecture from bottom-up. Where is this class used, and its cache?
>> Class comments at least help a lot along this track.
>>
>> I learned Smalltalk ith st-80 v2.3 and st-V, and I can say that
>> comments were not omitted in these distributions. Though the volume of
>> code was well below current Squeak trunk.
>> I'm not sure that increase of volume combined with lack of coments
>> makes beginner's life easier.
>>
>> Nicolas
>>
>>
>> 2013/1/22 Bert Freudenberg <bert at freudenbergs.de>:
>>  > Am 21.01.2013 um 22:29 schrieb "H. Hirzel" <hannes.hirzel at gmail.com>:
>> >
>> >> Thank you Bert for these concise answers. They will make up a good
>> >> bases for the comment.
>> >>
>> >> A follow up question:
>> >>
>> >> At which occasion is a snapshot done and what purpose does it serve?
>> >
>> > A snapshot is how MC models the contents of a package. Saving a package
>> means storing a snapshot of it. Loading means taking another snapshot of
>> what's currently in the image and comparing it to the stored snapshot,
>> then
>> filing in just the differences between the two.
>> >
>> > The MC code base is actually very readable, you should try having a
>> > look
>> at it. Nice example of OO design. I found the code to not even need
>> extensive comments, it is perfectly understandable without.
>> >
>> > - Bert -
>> >
>> >
>> >> --Hannes
>> >>
>> >> On 1/21/13, Bert Freudenberg <bert at freudenbergs.de> wrote:
>> >>>
>> >>> On 21.01.2013, at 13:40, "H. Hirzel" <hannes.hirzel at gmail.com> wrote:
>> >>>
>> >>>> And as we are at it
>> >>>>
>> >>>>   http://bugs.squeak.org/view.php?id=7560
>> >>>>
>> >>>> Monticello-Base contains the three classes
>> >>>>
>> >>>> MCDefinition
>> >>>> MCPackage
>> >>>> MCSnapshots
>> >>>>
>> >>>> All class comments are empty.
>> >>>
>> >>> A definition is a model for Smalltalk code. A package snapshot is a
>> >>> collection of these definitions.
>> >>>
>> >>>> What is the relationship between MCPackage and PackageInfo.
>> >>>
>> >>> MCPackage uses PackageInfo to find out which methods and classes
>> belong to a
>> >>> package.
>> >>>
>> >>>> What does
>> >>>>  MCDefinition clearInstances.
>> >>>> do?
>> >>>
>> >>> It nils out the quick-access cache to its subinstances. #allInstances
>> is
>> >>> very slow as it needs to scan the whole object memory, whereas
>> retrieving an
>> >>> instance from the "instances" WeakSet is O(1).
>> >>>
>> >>>> Why can this be done safely?
>> >>>
>> >>> Because re-using a definition is only a space optimization.
>> >>>
>> >>>> What is the impact of doing this?
>> >>>
>> >>> When loading/creating another snapshot, the definitions that are in
>> both
>> >>> snapshots will not be shared but occupy space twice.
>> >>>
>> >>> - Bert -
>> >>>
>> >>>> --Hannes
>> >>>>
>> >>>>
>> >>>> On 1/21/13, Nicolas Cellier <nicolas.cellier.aka.nice at gmail.com>
>> wrote:
>> >>>>> Trying to chasePointers of MCDefinition allSubInstances, I saw
>> several
>> >>>>> instances of MCPatchBrowser, MCVersionInspector, ...
>> >>>>> Though no such window is opened in my World, what's up?
>> >>>>>
>> >>>>> If I chase pointers of one of these ghost MCPatchBrowser keys, I
>> >>>>> see
>> >>>>> nothing but the opened inspectors and ObjectDependentsFields...
>> >>>>>
>> >>>>> I guess this must be exactly the same bug as
>> >>>>> http://bugs.squeak.org/view.php?id=7119 (see my own comments).
>> >>>>> The key of DependentsFields are weak, so they should be reclaimed.
>> >>>>> But what if the value points somehow to the key (no matter how
>> >>>>> deep)?
>> >>>>> Well, the key will never be reclaimed then.
>> >>>>>
>> >>>>> I don't feel comfortable with these dependencies... It's a nest of
>> >>>>> problems.
>> >>>>> In MVC, the dependents were maintained in model, so a cycle would
>> >>>>> be
>> >>>>> garbageCollected more easily...
>> >>>>>
>> >>>>> Nicolas
>> >>
>> >
>>
>>
>