2017-06-24 1:29 GMT+02:00 David T. Lewis lewis@mail.msen.com:
Can we follow Juan's guideance of of putting the documentation in a 'documentation' category in SystemDictionary, and then make that information visible from the help browsers? That will put the information in a well-known location for all distributions, and also make it presentable through the various help browsers.
Dave
Sure. Examples for generating topics from code comments are classes like HelpAPIDocumentation, which uses PackageAPIHelpTopic and friends to generate topics from class- and method comments. The generated topic hierarchy looks more suited for real API references, though (see below). So one might wish to write another adapter that generates a flatter hierarchy with nicer titles for the purpose.
{Class category name} {Class name} Instance side Class side
I would not put the documentation into SystemDictionary. This class is unused in Squeak images since the advent of Environments. Better create a new class.
On Fri, Jun 23, 2017 at 09:55:10PM +0200, Jakob Reschke wrote:
There are also the HelpTopic classes. WebClient has some IIRC. Since the texts reside in those classes, they would be placed next to the code in the package.
Am 23.06.2017 21:03 schrieb "Juan Vuletich" JuanVuletich@zoho.com:
On 6/23/2017 2:01 PM, tim Rowledge wrote:
On 23-06-2017, at 9:45 AM, Eliot Mirandaeliot.miranda@gmail.com
wrote:
To the general audience, I think information like the above is key to
being able to understand and exploit the system effectively, but where should it reside? Clearly "in my head" is not satisfactory. It belongs somewhere in the image, but it needs to be somewhere where people can find it and/or will look. Suggestions for an "architectural information" documentation section gratefully received. Object class>>whatIsAPrimitive might perhaps work or perhaps be overloaded.
A brief explanation in the sources as a comment for the class and/or
some relevant methods *plus* a link to a swiki page with the full details. The briefest explanation might well be as little as ???this is a quite complex issue; see swiki.squeak.org/85643505485"
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Useful random insult:- A .22 caliber intellect in a .357 Magnum world.
But this information is for Smalltalk developers, not just for VM developers. And urls might eventually break.
I think the full information on how to better use the VM belong in some file in VM sources, maybe one or several .md files. And Smalltalk systems using the VMs might chose to duplicate it in the image. I'd surely do it for Cuis.
This might be too much for Object class>>whatIsAPrimitive. I think some methods in a 'documentation' category in SystemDictionary would be better. Or one (or several) new classes, just for this. Better if we can share them in all the distributions: Squeak, Pharo, Newspeak and Cuis.
Thanks,
-- Juan Vuletich www.cuis-smalltalk.org https://github.com/Cuis-Smalltalk/Cuis-Smalltalk-Dev @JuanVuletich
On Sat, Jun 24, 2017 at 02:09:06AM +0200, Jakob Reschke wrote:
2017-06-24 1:29 GMT+02:00 David T. Lewis lewis@mail.msen.com:
Can we follow Juan's guideance of of putting the documentation in a 'documentation' category in SystemDictionary, and then make that information visible from the help browsers? That will put the information in a well-known location for all distributions, and also make it presentable through the various help browsers.
Dave
Sure. Examples for generating topics from code comments are classes like HelpAPIDocumentation, which uses PackageAPIHelpTopic and friends to generate topics from class- and method comments. The generated topic hierarchy looks more suited for real API references, though (see below). So one might wish to write another adapter that generates a flatter hierarchy with nicer titles for the purpose.
{Class category name} {Class name} Instance side Class side
I would not put the documentation into SystemDictionary. This class is unused in Squeak images since the advent of Environments. Better create a new class.
There are no instances of SystemDictionary any more, but the class still exists and is still useful. I think that Juan was suggesting it as a class that is known to exist in the various Squeak-related images, so it seems like a reasonable place to put some common documentation methods. Adding a new class would work also, but I suspect that adding a few methods under 'documentation' in SystemDictionary is more likely actually to be adopted across Squeak/Cuis/Pharo/Newspeak so I think it might be a good idea from that point of view.
Dave
Hi David, Jakob,
On Jun 23, 2017, at 5:59 PM, David T. Lewis lewis@mail.msen.com wrote:
On Sat, Jun 24, 2017 at 02:09:06AM +0200, Jakob Reschke wrote:
2017-06-24 1:29 GMT+02:00 David T. Lewis lewis@mail.msen.com:
Can we follow Juan's guideance of of putting the documentation in a 'documentation' category in SystemDictionary, and then make that information visible from the help browsers? That will put the information in a well-known location for all distributions, and also make it presentable through the various help browsers.
Dave
Sure. Examples for generating topics from code comments are classes like HelpAPIDocumentation, which uses PackageAPIHelpTopic and friends to generate topics from class- and method comments. The generated topic hierarchy looks more suited for real API references, though (see below). So one might wish to write another adapter that generates a flatter hierarchy with nicer titles for the purpose.
{Class category name} {Class name} Instance side Class side
I would not put the documentation into SystemDictionary. This class is unused in Squeak images since the advent of Environments. Better create a new class.
There are no instances of SystemDictionary any more, but the class still exists and is still useful. I think that Juan was suggesting it as a class that is known to exist in the various Squeak-related images, so it seems like a reasonable place to put some common documentation methods. Adding a new class would work also, but I suspect that adding a few methods under 'documentation' in SystemDictionary is more likely actually to be adopted across Squeak/Cuis/Pharo/Newspeak so I think it might be a good idea from that point of view.
I prefer SmalltalkImage as that contains the GC control routines so it will be easy to change their comments to say, e.g. Look on the class side for documentation on the GC architecture and facilities.
Dave
On Fri, Jun 23, 2017 at 06:09:29PM -0700, Eliot Miranda wrote:
Hi David, Jakob,
On Jun 23, 2017, at 5:59 PM, David T. Lewis lewis@mail.msen.com wrote:
On Sat, Jun 24, 2017 at 02:09:06AM +0200, Jakob Reschke wrote:
2017-06-24 1:29 GMT+02:00 David T. Lewis lewis@mail.msen.com:
Can we follow Juan's guideance of of putting the documentation in a 'documentation' category in SystemDictionary, and then make that information visible from the help browsers? That will put the information in a well-known location for all distributions, and also make it presentable through the various help browsers.
Dave
Sure. Examples for generating topics from code comments are classes like HelpAPIDocumentation, which uses PackageAPIHelpTopic and friends to generate topics from class- and method comments. The generated topic hierarchy looks more suited for real API references, though (see below). So one might wish to write another adapter that generates a flatter hierarchy with nicer titles for the purpose.
{Class category name} {Class name} Instance side Class side
I would not put the documentation into SystemDictionary. This class is unused in Squeak images since the advent of Environments. Better create a new class.
There are no instances of SystemDictionary any more, but the class still exists and is still useful. I think that Juan was suggesting it as a class that is known to exist in the various Squeak-related images, so it seems like a reasonable place to put some common documentation methods. Adding a new class would work also, but I suspect that adding a few methods under 'documentation' in SystemDictionary is more likely actually to be adopted across Squeak/Cuis/Pharo/Newspeak so I think it might be a good idea from that point of view.
I prefer SmalltalkImage as that contains the GC control routines so it will be easy to change their comments to say, e.g. Look on the class side for documentation on the GC architecture and facilities.
+1
That should be fine, since it also is present in all of the images.
Dave
vm-dev@lists.squeakfoundation.org
-
David T. Lewis -
Eliot Miranda -
Jakob Reschke