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

[Jakob Reschke]

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.

>
>
> 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 at zoho.com>:
>>
>> >
>> > On 6/23/2017 2:01 PM, tim Rowledge wrote:
>> > >
>> > >
>> > >> On 23-06-2017, at 9:45 AM, Eliot Miranda<eliot.miranda at 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 at 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
>> >
>> >
>> >
>