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

[David T. Lewis]

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.

Dave