[squeak-dev] Dynabook comments (was: The Inbox: Kernel-cmfcmf.1251.mcz)

David T. Lewis lewis at mail.msen.com
Tue Aug 6 22:50:47 UTC 2019


Changing the subject line.

On Mon, Aug 05, 2019 at 11:59:32PM -0500, Chris Muller wrote:
> Hi there, as we go to fix comments, may we take the opportunity to see if
> we'd like to change the nature of the comment in general?

I think it's a good idea to have better built-in documentation. I also
know that it can be a lot of work, and somebody has to be willing and
able to put the time and effort into making it happen. An unmaintained
set of documentation can be worse than none at all.

> 
> Here's where I'm going:  "built-in documentation".  For all #firstComments
> anyway, in methods throughout the system, if we would direct those
> particular comments toward the *Dynabook user*, something like:
> 
>    "Answer whether the receiver can be sent a message named aSymbol."

I tried exploring this:

   Object selectors collect: [ :sel | sel -> (Object firstCommentAt: sel) ]

The results suggest that the firstComment strings, when viewed outside the
context of a system browser, are not very meaningful.

> 
> then relatively simple systems can easily extract it to help connect users
> to a Dynabook experience.  Separate comments can be used to describe the
> 'dictionarys' or whatever implementation if desired, but since they
> wouldn't be the #firstComment, they wouldn't be presented in the user layer.
> 
> It's a simple but powerful leverage, what do you think?

I like the idea in principle, but in practice I would prefer to see energy
going into the Squeak help system, and possibly also into the built in
hyperlinking that can be embedded in existing comments. The help system
seems most promising to me overall, because it already has nice hooks
for displaying the organization and comments of exiting classes and
methods, and the help browser itself feels familiar and easy to use.

But overall: Good documentation is hard work, and it requires a lot
of dedication to make it happen. Different tools might help, but at
the end of the day somebody has to do the work.

Dave

> 
> Best,
>   Chris
> 
> On Mon, Aug 5, 2019 at 9:39 AM <commits at source.squeak.org> wrote:
> 
> > A new version of Kernel was added to project The Inbox:
> > http://source.squeak.org/inbox/Kernel-cmfcmf.1251.mcz
> >
> > ==================== Summary ====================
> >
> > Name: Kernel-cmfcmf.1251
> > Author: cmfcmf
> > Time: 5 August 2019, 4:39:08.95825 pm
> > UUID: eb7ae4e2-7697-7745-b4c3-4f9ce5975e2b
> > Ancestors: Kernel-mt.1250
> >
> > Clarify comment in Object>>respondsTo: to indicate that the method can
> > also be defined in a superclass.
> >
> > =============== Diff against Kernel-mt.1250 ===============
> >
> > Item was changed:
> >   ----- Method: Object>>respondsTo: (in category 'class membership') -----
> > + respondsTo: aSymbol
> > +       "Answer whether the method dictionary of the receiver's class or
> > any of its superclasses contains
> > - respondsTo: aSymbol
> > -       "Answer whether the method dictionary of the receiver's class
> > contains
> >         aSymbol as a message selector."
> >
> >         ^self class canUnderstand: aSymbol!
> >
> >
> >

> 



More information about the Squeak-dev mailing list