[Vm-dev] Where to put VM documentation? (was: instantiateClass:indexableSize: upper limit?)

[David T. Lewis]

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