In the Nautilus browser I have been working a bit on allowing Pillar for class comments. When browsing that part of Nautilus, I notice that there are some hooks for package comments in the getComments and addComments methods. Is there a history of "package comments" somewhere in the system? I was not able to find anything like that. Also it does not seem like there are any fields in the hierarchy of MBInfo that has anything to do with documentation. Is that the case? -- View this message in context: http://forum.world.st/Package-comments-tp4824353.html Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
I know little about the subject but Packages have been until recently only Strings. Now they were reified as objects, but as far as I saw, these objects didn't have comments as a part of them. â
Hello, Right now we do not have yet Package comments. But we should! MBInfo seems to be a private class of Versionner⦠For package comments we first need to evaluate the design space⦠e.g. where to store it in the image, how to store it in Monticello⦠Marcus
On 04 May 2015, at 18:33, Kasper Osterbye <kasper@itu.dk> wrote:
In the Nautilus browser I have been working a bit on allowing Pillar for class comments. When browsing that part of Nautilus, I notice that there are some hooks for package comments in the getComments and addComments methods.
Is there a history of "package comments" somewhere in the system? I was not able to find anything like that. Also it does not seem like there are any fields in the hierarchy of MBInfo that has anything to do with documentation. Is that the case?
Marcus Denker-4 wrote
Right now we do not have yet Package comments.
But we should!
MBInfo seems to be a private class of Versionnerâ¦
For package comments we first need to evaluate the design space⦠e.g. where to store it in the image, how to store it in Monticelloâ¦
OK - Makes sense.
From my perspective, the key to getting this of the ground is to make sure such comments can be written and read in Nautilus. The package objects used in Nautilus are from "RPackage". Thus, the problem, in my view reduces to: a) How to make room in RPackage for a comment field (add one more IV) b) How to integrate the storage of this field in connection with Monticello as Marcus writes.
Re b) It does seem that there several tools whihc make use of RPackage, Monicello is not one of them. There is a test suite RPackageMCSynchronisationTest (and subclasses) which deal with synchronizing RPackages and Monticello. In the MCMczWriter there is a method serializePackage: which should be able to store the comment, and similarly, loadpackage should be able to redo it. In essence extending the "package" member of a mcz file (a json structure) with an extra dictionary element. In addition, the RPackage<->MCPackage sync need to be extended to cover this extra field. I believe I will set some of my time aside to playing around with that idea unless someone tells me this is all very wrong and/or a waste of time. -- View this message in context: http://forum.world.st/Package-comments-tp4824353p4824636.html Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
Sergio Fedi wrote
If you need help, or just a buddy to tag along I can work with you.â
That would likely be very nice Sergio. I have opened a case in FogBugz (https://pharo.fogbugz.com/f/cases/15495/Package-comments) for this. I believe the result of this work will end up as some kind of slice. I will set up a project on smalltalk hub where this can be done. Right now is time for the next meeting - sighs. -- View this message in context: http://forum.world.st/Package-comments-tp4824353p4824741.html Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
On 05 May 2015, at 17:14, Kasper Osterbye <kasper@itu.dk> wrote:
Marcus Denker-4 wrote
Right now we do not have yet Package comments.
But we should!
MBInfo seems to be a private class of Versionnerâ¦
For package comments we first need to evaluate the design space⦠e.g. where to store it in the image, how to store it in Monticelloâ¦
OK - Makes sense.
From my perspective, the key to getting this of the ground is to make sure such comments can be written and read in Nautilus. The package objects used in Nautilus are from "RPackage". Thus, the problem, in my view reduces to: a) How to make room in RPackage for a comment field (add one more IV) b) How to integrate the storage of this field in connection with Monticello as Marcus writes.
Re b) It does seem that there several tools whihc make use of RPackage, Monicello is not one of them. There is a test suite RPackageMCSynchronisationTest (and subclasses) which deal with synchronizing RPackages and Monticello.
But there is a one-to-one mapping between MCPackage and RPackage⦠we need to take care to keep Monticello compatible. (Else it would be so nice if MC would share the model with everyone else.. it models, yet again, classe, methods, packagesâ¦)
In the MCMczWriter there is a method serializePackage: which should be able to store the comment, and similarly, loadpackage should be able to redo it. In essence extending the "package" member of a mcz file (a json structure) with an extra dictionary element.
In addition, the RPackage<->MCPackage sync need to be extended to cover this extra field.
Yes. Due to backward compatibility, we need to make sure to not save it in the MC model itself but as an additional entity in the zip file, that then other smalltalk can ignore. Marcus
Le 5 mai 2015 à 17:14, Kasper Osterbye a écrit :
Marcus Denker-4 wrote
Right now we do not have yet Package comments.
But we should!
MBInfo seems to be a private class of Versionnerâ¦
For package comments we first need to evaluate the design space⦠e.g. where to store it in the image, how to store it in Monticelloâ¦
OK - Makes sense.
From my perspective, the key to getting this of the ground is to make sure such comments can be written and read in Nautilus. The package objects used in Nautilus are from "RPackage". Thus, the problem, in my view reduces to: a) How to make room in RPackage for a comment field (add one more IV) b) How to integrate the storage of this field in connection with Monticello as Marcus writes.
I don't think is the good way to do that. We are working on adding meta-data to packages. These meta-data includes a package description (or comment) but also a lot of other data. You will not be able to store everything in rpackage inst. var. And of course, there is also the problem that Monticello is not able to store meta-data (e.g. STON files). For now, the best option is to use a PackageManifest. If you want to allow package comments in Nautilus, I would display the content of the description method of the package manifest if available. Christophe.
On 06 May 2015, at 10:53, Christophe Demarey <Christophe.Demarey@inria.fr> wrote:
Le 5 mai 2015 à 17:14, Kasper Osterbye a écrit :
Marcus Denker-4 wrote
Right now we do not have yet Package comments.
But we should!
MBInfo seems to be a private class of Versionnerâ¦
For package comments we first need to evaluate the design space⦠e.g. where to store it in the image, how to store it in Monticelloâ¦
OK - Makes sense.
From my perspective, the key to getting this of the ground is to make sure such comments can be written and read in Nautilus. The package objects used in Nautilus are from "RPackage". Thus, the problem, in my view reduces to: a) How to make room in RPackage for a comment field (add one more IV) b) How to integrate the storage of this field in connection with Monticello as Marcus writes.
I don't think is the good way to do that. We are working on adding meta-data to packages. These meta-data includes a package description (or comment) but also a lot of other data. You will not be able to store everything in rpackage inst. var. And of course, there is also the problem that Monticello is not able to store meta-data (e.g. STON files). For now, the best option is to use a PackageManifest.
If you want to allow package comments in Nautilus, I would display the content of the description method of the package manifest if available.
Yes⦠this could be the easiest for now. Then as a second step, we add support to store resources in Monticello. Marcus
2015-05-06 13:08 GMT+02:00 Marcus Denker <marcus.denker@inria.fr>:
On 06 May 2015, at 10:53, Christophe Demarey < Christophe.Demarey@inria.fr> wrote:
Le 5 mai 2015 à 17:14, Kasper Osterbye a écrit :
Marcus Denker-4 wrote
Right now we do not have yet Package comments.
But we should!
MBInfo seems to be a private class of Versionnerâ¦
For package comments we first need to evaluate the design space⦠e.g. where to store it in the image, how to store it in Monticelloâ¦
OK - Makes sense.
From my perspective, the key to getting this of the ground is to make sure such comments can be written and read in Nautilus. The package objects used in Nautilus are from "RPackage". Thus, the problem, in my view reduces to: a) How to make room in RPackage for a comment field (add one more IV) b) How to integrate the storage of this field in connection with Monticello as Marcus writes.
I don't think is the good way to do that. We are working on adding meta-data to packages. These meta-data includes a package description (or comment) but also a lot of other data. You will not be able to store everything in rpackage inst. var. And of course, there is also the problem that Monticello is not able to store meta-data (e.g. STON files). For now, the best option is to use a PackageManifest.
If you want to allow package comments in Nautilus, I would display the content of the description method of the package manifest if available.
Yes⦠this could be the easiest for now.
Then as a second step, we add support to store resources in Monticello.
Marcus
Adding metadata to MC cannot be very difficult, MC already carries plenty of metadata ;) Coordination with other dialects (squeak/gemstone/...) would be welcome, because i'm sure that every dialect would benefit from package comments, or already has package comments (vw along with many other properties). No long discussion required, if no consensus, just let Pharo lead. I remember that Bert has experimented adding a comment to PackageInfo, but I don't know in which state it did end up (MC-wise). Nicolas
demarey wrote
If you want to allow package comments in Nautilus, I would display the content of the description method of the package manifest if available.
It would be great to leverage on something already taking place. Are you talking about class PackageManifest? I can see that RPackage has a method which will give me a PackageManifest (or create a new one). I have not been able to spot "the description method of the package manifest" (as mentioned by Marcus). Mostly those Manifest classes seems to be used for other purposes than documentation. I'll try out a few things to see how it can work, my reading of the "TheManifestBuilder>>createManifestNamed:" shows that manifests would be very suited for this documentation purpose, as it actually create a ManifestClass in the package. I believe this class is stored in Monticello like any other class. For the time being I found no instances of PackageManifest, so it is a bit unclear to me how these Manifest classes store any data? -- View this message in context: http://forum.world.st/Package-comments-tp4824353p4824772.html Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
Le 6 mai 2015 à 13:21, Kasper Osterbye a écrit :
demarey wrote
If you want to allow package comments in Nautilus, I would display the content of the description method of the package manifest if available.
It would be great to leverage on something already taking place. Are you talking about class PackageManifest? I can see that RPackage has a method which will give me a PackageManifest (or create a new one). I have not been able to spot "the description method of the package manifest" (as mentioned by Marcus). Mostly those Manifest classes seems to be used for other purposes than documentation.
Manifest classes were introduced to manage code critics false positives.
I'll try out a few things to see how it can work, my reading of the "TheManifestBuilder>>createManifestNamed:" shows that manifests would be very suited for this documentation purpose, as it actually create a ManifestClass in the package. I believe this class is stored in Monticello like any other class.
right
For the time being I found no instances of PackageManifest, so it is a bit unclear to me how these Manifest classes store any data?
Indeed. There are PackageManifest classes only for projects managing code critics false positives. I created the PackageManifest class to start the decoupling between the manifest and critics, but there is not yet a lot of other tools / project using it (but it will come). Data is stored in raw strings in methods (instance side) of the Manifest. ex: ManifestKernel>>#description ^ 'I am the description of the Pharo Kernel package.'
Hi, as you know Iâm working on QualityAssistant, and at the moment the current structure of false positives in Manifest in not good enough for me. So I plant to reimplement it. Should I follow some guidelines? Because you are introducing this new package manifest, and I think that it could make sense if Iâll give you a feedback whether I works well for my needs. Uko
On 06 May 2015, at 13:56, Christophe Demarey <Christophe.Demarey@inria.fr> wrote:
Le 6 mai 2015 à 13:21, Kasper Osterbye a écrit :
demarey wrote
If you want to allow package comments in Nautilus, I would display the content of the description method of the package manifest if available.
It would be great to leverage on something already taking place. Are you talking about class PackageManifest? I can see that RPackage has a method which will give me a PackageManifest (or create a new one). I have not been able to spot "the description method of the package manifest" (as mentioned by Marcus). Mostly those Manifest classes seems to be used for other purposes than documentation.
Manifest classes were introduced to manage code critics false positives.
I'll try out a few things to see how it can work, my reading of the "TheManifestBuilder>>createManifestNamed:" shows that manifests would be very suited for this documentation purpose, as it actually create a ManifestClass in the package. I believe this class is stored in Monticello like any other class.
right
For the time being I found no instances of PackageManifest, so it is a bit unclear to me how these Manifest classes store any data?
Indeed. There are PackageManifest classes only for projects managing code critics false positives. I created the PackageManifest class to start the decoupling between the manifest and critics, but there is not yet a lot of other tools / project using it (but it will come).
Data is stored in raw strings in methods (instance side) of the Manifest. ex: ManifestKernel>>#description ^ 'I am the description of the Pharo Kernel package.'
Independent of package comments, the ManifestClasses are a good idea I think. I also think they have not yet found their final design. Let me summarize my impressions so far (perhaps this need to go to a different thread). a) All package manifests are subclasses of "PackageManifest" - good idea. b) The principle of storing the manifest properties as literals in methods is surprising, but has its advantages. However, no general functionality for storing those values seems to be in place. c) The class "TheManifestBuilder" seems to be a key class, and has a lot of functionality for the quality assistant (I presume that is what they are used for - I have not looked in that corner of the system yet). I think the manifest builder need to be split into a family of builders, a general builder which has the functionality to create and query manifest classes, and a set of builders for each (set of) properties of manifest classes. The QualityAssistant would then have its own subclass, and package comments would have its subclass. For now, I believe I will experiment with merely having a package comment category on TheManifestBuilder. -- View this message in context: http://forum.world.st/Package-comments-tp4824353p4825058.html Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
Le 7/5/15 17:04, Kasper Osterbye a écrit :
Independent of package comments, the ManifestClasses are a good idea I think. I also think they have not yet found their final design. Let me summarize my impressions so far (perhaps this need to go to a different thread).
a) All package manifests are subclasses of "PackageManifest" - good idea. b) The principle of storing the manifest properties as literals in methods is surprising, but has its advantages. However, no general functionality for storing those values seems to be in place. c) The class "TheManifestBuilder" seems to be a key class, and has a lot of functionality for the quality assistant (I presume that is what they are used for - I have not looked in that corner of the system yet).
What you should see is that originally the PackageManifest did not exist so Manifest classes should not hold behavior. They are just data container.
I think the manifest builder need to be split into a family of builders, a general builder which has the functionality to create and query manifest classes, and a set of builders for each (set of) properties of manifest classes. The QualityAssistant would then have its own subclass, and package comments would have its subclass.
Why not :) But you can packaged methods in the PackageManifestBuilder so I'm not sure that we need different subclasses.
For now, I believe I will experiment with merely having a package comment category on TheManifestBuilder.
-- View this message in context: http://forum.world.st/Package-comments-tp4824353p4825058.html Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
Sergio Fedi and I are now working on this. As part of the work, we need a "default package comment", akin the the default class comment. The class comment is inspired by CRC idea. Translating CRC to a PRC, we suggest the following, and ask for comments from the community. As I believe we will by the end of the year have a inworld pillar renderer which is fairly stable, the default PRC template could be: 'Please comment me using the following ""template"", ''inspired'' by Class Responsibility Collaborator (CRC) design: !Package XXX, part of (reference to main package if one exist) one line description: For example, I'm xxx package, containing the hierarchy of visitor objects. ;Responsibiliies :Three sentences about my main responsibility, what I'm doing, what classes do I offer. ;Collaborators :State my related packages, and which classes are the ones used from the outside of the package. !!Public API - message one in class one - message two in class two - what is the way to use this package. One simple example is simply gorgeous. Or refer to which package is the main package if there are several packages in play !!Internal Representation and Key Implementation Points. -Implementation Points, in particular references to classes with good class comments.' Will this work? Best, Sergio & Kasper -- View this message in context: http://forum.world.st/Package-comments-tp4824353p4825838.html Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
Le 11/5/15 20:10, Kasper Osterbye a écrit :
Sergio Fedi and I are now working on this.
As part of the work, we need a "default package comment", akin the the default class comment. The class comment is inspired by CRC idea. Translating CRC to a PRC, we suggest the following, and ask for comments from the community. As I believe we will by the end of the year have a inworld pillar renderer which is fairly stable, the default PRC template could be:
Coooooool :)
'Please comment me using the following ""template"", ''inspired'' by Class Responsibility Collaborator (CRC) design:
!Package XXX, part of (reference to main package if one exist) I did not get "
(reference to main package if one exist) "
one line description: For example, I'm xxx package, containing the hierarchy of visitor objects. What are the public main classes?
;Responsibiliies :Three sentences about my main responsibility, what I'm doing, what classes do I offer. ;Collaborators :State my related packages, and which classes are the ones used from the outside of the package.
!!Public API
- message one in class one - message two in class two - what is the way to use this package.
One simple example is simply gorgeous. Or refer to which package is the main package if there are several packages in play
!!Internal Representation and Key Implementation Points.
-Implementation Points, in particular references to classes with good class comments.'
Will this work?
Best, Sergio & Kasper
-- View this message in context: http://forum.world.st/Package-comments-tp4824353p4825838.html Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
stepharo wrote
!Package XXX, part of (reference to main package if one exist) I did not get "
(reference to main package if one exist)
"
Perhaps it should be: "!Package XXX, (part of reference to main package if one exist)" I often see a handful of packages named "XXXX-YYYY", "XXXX-ZZZZ", "XXXX-AAAA", etc. and a reference to which of these packages is the main/root/start/core package is what I tried to get at. stepharo wrote
one line description: For example, I'm xxx package, containing the hierarchy of visitor objects. What are the public main classes?
There are no such thing :-) - just as there is no "private methods" in smalltalk. But in conceptually, in a package there are classes which are intended to be used and referred from outside of the package, and classes that realize internals in the package. -- View this message in context: http://forum.world.st/Package-comments-tp4824353p4825917.html Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
Le 12 mai 2015 à 06:44, Kasper Osterbye a écrit :
stepharo wrote
one line description: For example, I'm xxx package, containing the hierarchy of visitor objects. What are the public main classes?
There are no such thing :-) - just as there is no "private methods" in smalltalk. But in conceptually, in a package there are classes which are intended to be used and referred from outside of the package, and classes that realize internals in the package.
Here I would rather see the entry point of the package: the core class(es) and how to use it
On 12 maj, 2015, at 11:17 , demarey [via Smalltalk] <ml-node+s1294792n4825947h65@n4.nabble.com<mailto:ml-node+s1294792n4825947h65@n4.nabble.com>> wrote: Here I would rather see the entry point of the package: the core class(es) and how to use it Great - I like the term âEntry pointâ - just what we were looking for. -- View this message in context: http://forum.world.st/Package-comments-tp4824353p4825948.html Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
Try to have it so users don't have to delete much, just extend what is there. On Tue, May 12, 2015 at 2:10 AM, Kasper Osterbye <kasper@itu.dk> wrote:
Sergio Fedi and I are now working on this.
As part of the work, we need a "default package comment", akin the the default class comment. The class comment is inspired by CRC idea. Translating CRC to a PRC, we suggest the following, and ask for comments from the community. As I believe we will by the end of the year have a inworld pillar renderer which is fairly stable, the default PRC template could be: 'Please comment me using the following ""template"", ''inspired'' by Class Responsibility Collaborator (CRC) design:
'inspired'' by Class Responsibility Collaborator (CRC) design, written in first-person narrative:
!Package XXX, part of (reference to main package if one exist) one line description: For example, I'm xxx package, containing the hierarchy of visitor objects.
One line description: I'm Xyz package, providing widgets that ... (Leave "Part of package" for Collaborators (see below) )
;Responsibiliies :Three sentences about my main responsibility, what I'm doing, what classes do I offer.
(Three sentences is not much to talk about all the package's classes. How about...) I offer services for ...
;Collaborators
:State my related packages, and which classes are the ones used from the
outside of the package.
I'm part of Abc package ... My related packages are ... My entry points are ...
!!Public API
- message one in class one - message two in class two - what is the way to use this package.
One simple example is simply gorgeous. Or refer to which package is the main package if there are several packages in play
!!Internal Representation and Key Implementation Points.
-Implementation Points, in particular references to classes with good class comments.'
Will this work?
Nice initiative. cheers -ben
Kasper our idea is that each package should have meta-data: - default code formatting - false positive for rules - and of course package comment. So for now the simplest thing we did was to add a class called ManifestXXX for packageXXX. This way it is versionned with the classes and we can browse it.... Stef Le 4/5/15 18:33, Kasper Osterbye a écrit :
In the Nautilus browser I have been working a bit on allowing Pillar for class comments. When browsing that part of Nautilus, I notice that there are some hooks for package comments in the getComments and addComments methods.
Is there a history of "package comments" somewhere in the system? I was not able to find anything like that. Also it does not seem like there are any fields in the hierarchy of MBInfo that has anything to do with documentation. Is that the case?
-- View this message in context: http://forum.world.st/Package-comments-tp4824353.html Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
Does this mean that we should focus on adding the comments on this ManifestXXX class? (instead of other implementations)â
On 6 maj, 2015, at 21:27 , Sergio Fedi [via Smalltalk] <ml-node+s1294792n4824882h50@n4.nabble.com> wrote:
Does this mean that we should focus on adding the comments on this ManifestXXX class? (instead of other implementations)â Yes, that seems like the right approach to me.
I believe we could add some methods to âTheManifestBuilderâ to get/set a package comment. If we put the methods in a special category in that builder, we should be ok. These methods are then what we call from the get/add comment in the AbstractNautilusUI class. (Then I have some reservations to the details of how ManifestXXX are done, but that is for some other time - package comments should live here, and it is easy to work with.) -- View this message in context: http://forum.world.st/Package-comments-tp4824353p4824950.html Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
On 6 maj, 2015, at 21:23 , stepharo [via Smalltalk] <ml-node+s1294792n4824878h26@n4.nabble.com> wrote:
our idea is that each package should have meta-data: - default code formatting - false positive for rules - and of course package comment.
So for now the simplest thing we did was to add a class called ManifestXXX for packageXXX. This way it is versionned with the classes and we can browse it....
Stef Thanks for the clarification. Iâll work with Sergio Fedi on this one, it seems to be a very simple thing (very little, well isolated code).
Best, Kasper -- View this message in context: http://forum.world.st/Package-comments-tp4824353p4824949.html Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
participants (8)
-
Ben Coman -
Christophe Demarey -
Kasper Osterbye -
Marcus Denker -
Nicolas Cellier -
Sergio Fedi -
stepharo -
Yuriy Tymchuk