The Inbox: Kernel-cmfcmf.1251.mcz

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

The Inbox: Kernel-cmfcmf.1251.mcz

commits-2
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!


Reply | Threaded
Open this post in threaded view
|

Re: The Inbox: Kernel-cmfcmf.1251.mcz

Chris Muller-3
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?

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."

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?

Best,
  Chris

On Mon, Aug 5, 2019 at 9:39 AM <[hidden email]> 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!




Reply | Threaded
Open this post in threaded view
|

Re: The Inbox: Kernel-cmfcmf.1251.mcz

marcel.taeumel
One can always send any message to any receiver. :-)

The question is whether the answer can be meaningful or not. Can a client expect a meaningful answer from such a message send? Neither mentioning method dictionary nor superclasses help figure out when and why to send #respondsTo: to an object. Only Behavior is the domain and place to talk about method dictionary and superclasses. The comment in #canUnderstand: does already mention method dictionary and superclasses.

Just my two cents. :-)

Best,
Marcel

Am 06.08.2019 07:00:19 schrieb Chris Muller <[hidden email]>:

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?

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."

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?

Best,
  Chris

On Mon, Aug 5, 2019 at 9:39 AM <[hidden email]> 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!




Reply | Threaded
Open this post in threaded view
|

Re: The Inbox: Kernel-cmfcmf.1251.mcz

Chris Muller-3


On Tue, Aug 6, 2019 at 3:18 AM Marcel Taeumel <[hidden email]> wrote:
One can always send any message to any receiver. :-)

Sure, a Smalltalk developer gets that.  But from the context of what's meaningful to a Dynabook user simply interested in using Squeak objects as an app, they simply know they don't want to see that "does not understand" error message.  "Can send" is synonymous enough with that.  But my main point is not about what exact words, but about the idea of speaking to that specific audience through the #firstComment.
 

The question is whether the answer can be meaningful or not. Can a client expect a meaningful answer from such a message send?

Right.  The thrust of my post is that the "client" in your statement above is a Dynabook user, and _not_ a Smalltalk developer.
 
Neither mentioning method dictionary nor superclasses help figure out when and why to send #respondsTo: to an object. Only Behavior is the domain and place to talk about method dictionary and superclasses. The comment in #canUnderstand: does already mention method dictionary and superclasses.

Users are only concerned with "sending messages to objects", nothing else.  Those Dictionary's are below the level of what they care about.  Even the notion of inheritance (superclasses) will cause their eyes to glaze over.  Sending messages to concrete instances is where the rubber meets the road.  The #firstComment is a opportunity to open up the Squeak class-library to a new group of people, without affecting our ability to talk to Smalltalk developers in the 2nd - nth comments.  But most of the time, I'm sure the one single user-centric comment is sufficient for both groups.

 - Chris

 

Just my two cents. :-)

Best,
Marcel

Am 06.08.2019 07:00:19 schrieb Chris Muller <[hidden email]>:

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?

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."

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?

Best,
  Chris

On Mon, Aug 5, 2019 at 9:39 AM <[hidden email]> 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!





Reply | Threaded
Open this post in threaded view
|

Dynabook comments (was: The Inbox: Kernel-cmfcmf.1251.mcz)

David T. Lewis
In reply to this post by Chris Muller-3
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 <[hidden email]> 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!
> >
> >
> >

>


Reply | Threaded
Open this post in threaded view
|

Re: Dynabook comments (was: The Inbox: Kernel-cmfcmf.1251.mcz)

Chris Muller-3

Changing the subject line.

Thank you!
 

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.

Yes.
 

>
> 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.\

Yes, context is everything.

  A developer reading code in a system browser, 
  a data engineer using a query language that wraps a Smalltalk API,
  or a user using a thin layer UI interface that wraps a Smalltalk API

In those contexts, firstComments could be given extra care to explain the usage of the method, instead of its code.

Note the proposal is only for public methods.


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

I think the help system is great and would also like to see more things there.

This is just a suggestion for Smalltalk developers to consider adopting as a practice when already writing their next firstComment of a method.  Systems nowadays are including "metadata".  I know we have Pragmas but that's a big project like what you were alluding to.  If this caught on as a good Smalltalk practice, over time, these comments could become very useful in those aforementioned contexts.

Best,
  Chris
 


Reply | Threaded
Open this post in threaded view
|

Re: The Inbox: Kernel-cmfcmf.1251.mcz

marcel.taeumel
In reply to this post by Chris Muller-3
Hi Chris,

I think we mean the same here. I just wanted to add the word "meaningful" to your suggestions:

 "Answer whether the receiver can be sent a message named aSymbol and expect a meaningful answer."

Best,
Marcel

Am 06.08.2019 22:05:35 schrieb Chris Muller <[hidden email]>:



On Tue, Aug 6, 2019 at 3:18 AM Marcel Taeumel <[hidden email]> wrote:
One can always send any message to any receiver. :-)

Sure, a Smalltalk developer gets that.  But from the context of what's meaningful to a Dynabook user simply interested in using Squeak objects as an app, they simply know they don't want to see that "does not understand" error message.  "Can send" is synonymous enough with that.  But my main point is not about what exact words, but about the idea of speaking to that specific audience through the #firstComment.
 

The question is whether the answer can be meaningful or not. Can a client expect a meaningful answer from such a message send?

Right.  The thrust of my post is that the "client" in your statement above is a Dynabook user, and _not_ a Smalltalk developer.
 
Neither mentioning method dictionary nor superclasses help figure out when and why to send #respondsTo: to an object. Only Behavior is the domain and place to talk about method dictionary and superclasses. The comment in #canUnderstand: does already mention method dictionary and superclasses.

Users are only concerned with "sending messages to objects", nothing else.  Those Dictionary's are below the level of what they care about.  Even the notion of inheritance (superclasses) will cause their eyes to glaze over.  Sending messages to concrete instances is where the rubber meets the road.  The #firstComment is a opportunity to open up the Squeak class-library to a new group of people, without affecting our ability to talk to Smalltalk developers in the 2nd - nth comments.  But most of the time, I'm sure the one single user-centric comment is sufficient for both groups.

 - Chris

 

Just my two cents. :-)

Best,
Marcel

Am 06.08.2019 07:00:19 schrieb Chris Muller <[hidden email]>:

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?

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."

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?

Best,
  Chris

On Mon, Aug 5, 2019 at 9:39 AM <[hidden email]> 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!