Squeak - Dev - The Trunk: Kernel-eem.1316.mcz

The Trunk: Kernel-eem.1316.mcz

Classic

List

Threaded

30 messages Options

commits-2

The Trunk: Kernel-eem.1316.mcz

Eliot Miranda uploaded a new version of Kernel to project The Trunk:
http://source.squeak.org/trunk/Kernel-eem.1316.mcz

==================== Summary ====================

Name: Kernel-eem.1316
Author: eem
Time: 11 March 2020, 1:02:37.986482 pm
UUID: daa453eb-09f1-446b-bc64-6f6c0298daf2
Ancestors: Kernel-nice.1315

Improve Object class-side documentation for primtiives.

=============== Diff against Kernel-nice.1315 ===============

Item was changed:
----- Method: Object class>>howToModifyPrimitives (in category 'documentation') -----
howToModifyPrimitives
"You are allowed to write methods which specify primitives, but please use
caution. If you make a subclass of a class which contains a primitive method,
the subclass inherits the primitive. The message which is implemented
primitively may be overridden in the subclass (E.g., see at:put: in String's
subclass Symbol). The primitive behavior can be invoked using super (see
Symbol string:).

A class which attempts to mimic the behavior of another class without being
its subclass may or may not be able to use the primitives of the original class.
In general, if the instance variables read or written by a primitive have the
same meanings and are in the same fields in both classes, the primitive will
work.

For certain frequently used 'special selectors', the compiler emits a
send-special-selector bytecode instead of a send-message bytecode. Special
selectors were created because they offer two advantages. First, code which
sends special selectors compiles into fewer bytes than normal. Second, for
some pairs of receiver classes and special selectors, the interpreter jumps
directly to a primitive routine without looking up the method in the class,
and the just-in-time (JIT) compiler (if in use) may emit code to directly execute
+ the primitive. At least in the interpreter this is much faster than a normal
- the primitive. At least in the interpeeter this is much faster than a normal
message lookup. In both the interpreter and the JIT send-special-selector,
+ conditional branch pairs are short-circuited for the comparison selectors when
+ applied to SmallIntegers or Floats.
- conditional branch pairs are short-circuited for the comparison selectors.

+ A selector which is a special selector solely in order to save space has
- A selector which is a special selector solely in order to save space has a
normal behavior. Methods whose selectors are special in order to
+ gain speed contain the comment, 'No Lookup'. When the virtual machine
- gain speed contain the comment, 'No Lookup'. When the interpreter
encounters a send-special-selector bytecode, it checks the class of the
receiver and the selector. If the class-selector pair is a no-lookup pair,
then the interpreter swiftly jumps to the routine which implements the
corresponding primitive. (A special selector whose receiver is not of the
right class to make a no-lookup pair, is looked up normally). The pairs are
listed below. No-lookup methods contain a primitive number specification,
<primitive: xx>, which is redundant. Since the method is not normally looked
up, deleting the primitive number specification cannot prevent this
primitive from running. If a no-lookup primitive fails, the method is looked
up normally, and the expressions in it are executed.

No Lookup pairs of (class, selector)

SmallInteger and Float with any of + - * /
SmallInteger with any of \\ bitOr: bitShift: bitAnd: // @
SmallInteger and Float with any of = ~= > < >= <=
Any class with == ~~ class
Point with either of x y (interpreter only)
BlockClosure with either of value value: (interpreter only)
"

self error: 'comment only'!

Item was changed:
----- Method: Object class>>whatIsAPrimitive (in category 'documentation') -----
whatIsAPrimitive
"Some messages in the system are responded to primitively. A primitive
+ response is performed directly by the virtual machine rather than by
+ evaluating expressions in a method. The methods for these messages
+ indicate the presence of a primitive response by including one of
+ <primitive: N>
+ <primitive: N error: errorCode>
+ <primitive: 'primitiveName' module: 'module name'>
+ <primitive: 'primitiveName' module: 'module name' error: errorCode>
+ before the first expression in the method.
- response is performed directly by the interpreter rather than by evaluating
- expressions in a method. The methods for these messages indicate the
- presence of a primitive response by including <primitive: xx> before the
- first expression in the method.

+ Primitives exist for several reasons. Certain basic or 'primitive' operations
+ cannot be performed in any other way. Smalltalk without primitives can
+ move values from one variable to another, but cannot add two SmallIntegers
+ together. Many methods for arithmetic and comparison between numbers
+ are primitives. Some primitives allow Smalltalk to communicate with I/O
+ devices such as the disk, the display, and the keyboard. Some primitives
+ exist only to make the system run faster; each does the same thing as a
+ certain Smalltalk method, and its implementation as a primitive is optional.
+
+ When the Smalltalk virtual machine begins to execute a method which
+ specifies a primitive response, it tries to perform the primitive action and to
+ return a result. If the routine in the virtual machine for this primitive is
+ successful, it will return a value and the expressions in the method will not
+ be evaluated. If the primitive routine is not successful, the primitive 'fails',
+ and the Smalltalk expressions in the method are executed instead. These
+ expressions are evaluated as though the primitive routine had not been called.
+
+ The Smalltalk code that is evaluated when a primitive fails usually anticipates
+ why that primitive might fail. If the primitive is optional, the expressions in the
+ method do exactly what the primitive would have done (See Number @). If the
+ primitive only works on certain classes of arguments, the Smalltalk code tries
+ to coerce the argument or appeals to a superclass to find a more general way
+ of doing the operation (see SmallInteger +). If the primitive is never supposed
+ to fail, the expressions signal an error (see e.g. SmallInteger asFloat).
+
- Primitives exist for several reasons. Certain basic or 'primitive'
- operations cannot be performed in any other way. Smalltalk without
- primitives can move values from one variable to another, but cannot add two
- SmallIntegers together. Many methods for arithmetic and comparison
- between numbers are primitives. Some primitives allow Smalltalk to
- communicate with I/O devices such as the disk, the display, and the keyboard.
- Some primitives exist only to make the system run faster; each does the same
- thing as a certain Smalltalk method, and its implementation as a primitive is
- optional.
-
- When the Smalltalk interpreter begins to execute a method which specifies a
- primitive response, it tries to perform the primitive action and to return a
- result. If the routine in the interpreter for this primitive is successful,
- it will return a value and the expressions in the method will not be evaluated.
- If the primitive routine is not successful, the primitive 'fails', and the
- Smalltalk expressions in the method are executed instead. These
- expressions are evaluated as though the primitive routine had not been
- called.
-
- The Smalltalk code that is evaluated when a primitive fails usually
- anticipates why that primitive might fail. If the primitive is optional, the
- expressions in the method do exactly what the primitive would have done (See
- Number @). If the primitive only works on certain classes of arguments, the
- Smalltalk code tries to coerce the argument or appeals to a superclass to find
- a more general way of doing the operation (see SmallInteger +). If the
- primitive is never supposed to fail, the expressions signal an error (see
- SmallInteger asFloat).
-
Each method that specifies a primitive has a comment in it. If the primitive is
optional, the comment will say 'Optional'. An optional primitive that is not
+ implemented always fails, and the Smalltalk expressions do the work instead.
- implemented always fails, and the Smalltalk expressions do the work
- instead.

+ If a primitive is not optional, the comment will say, 'Essential'. If the primitive is
+ so required, the comment will say 'Do not override in a subclass'. Some methods
+ will have the comment, 'No Lookup'. See Object howToModifyPrimitives for an
+ explanation of special selectors which are not looked up.
- If a primitive is not optional, the comment will say, 'Essential'. Some
- methods will have the comment, 'No Lookup'. See Object
- howToModifyPrimitives for an explanation of special selectors which are
- not looked up.

+ The comments in the SmallInteger primitives say 'Fails if result is not a SmallInteger',
+ even though the implementor has the option to construct a LargePositiveInteger.
+ For further information on primitives, see the 'Primitive Methods' part of the
+ chapter on the formal specification of the virtual machine in
+ Smalltalk-80: The Language and its Implementation."
- For the primitives for +, -, *, and bitShift: in SmallInteger, and truncated
- in Float, the primitive constructs and returns a 16-bit
- LargePositiveInteger when the result warrants it. Returning 16-bit
- LargePositiveIntegers from these primitives instead of failing is
- optional in the same sense that the LargePositiveInteger arithmetic
- primitives are optional. The comments in the SmallInteger primitives say,
- 'Fails if result is not a SmallInteger', even though the implementor has the
- option to construct a LargePositiveInteger. For further information on
- primitives, see the 'Primitive Methods' part of the chapter on the formal
- specification of the interpreter in the Smalltalk book."

self error: 'comment only'!

Christoph Thiede

self error: 'comment only' (was: The Trunk: Kernel-eem.1316.mcz)

I really appreciate elaborate documentation comments like this. However, is it really necessary and seasonable to store them in methods whose only purpose is to hold a comment? IMHO, this is a quite abusive way to declare methods. Why can't we put this into class comments?

Best,

Christoph

Von: Squeak-dev <[hidden email]> im Auftrag von [hidden email] <[hidden email]>
Gesendet: Mittwoch, 11. März 2020 21:03 Uhr
An: [hidden email]; [hidden email]
Betreff: [squeak-dev] The Trunk: Kernel-eem.1316.mcz

Eliot Miranda uploaded a new version of Kernel to project The Trunk:
http://source.squeak.org/trunk/Kernel-eem.1316.mcz

==================== Summary ====================

Name: Kernel-eem.1316
Author: eem
Time: 11 March 2020, 1:02:37.986482 pm
UUID: daa453eb-09f1-446b-bc64-6f6c0298daf2
Ancestors: Kernel-nice.1315

Improve Object class-side documentation for primtiives.

=============== Diff against Kernel-nice.1315 ===============

Item was changed:
----- Method: Object class>>howToModifyPrimitives (in category 'documentation') -----
howToModifyPrimitives
         "You are allowed to write methods which specify primitives, but please use
         caution. If you make a subclass of a class which contains a primitive method,
         the subclass inherits the primitive. The message which is implemented
         primitively may be overridden in the subclass (E.g., see at:put: in String's
         subclass Symbol). The primitive behavior can be invoked using super (see
         Symbol string:).

         A class which attempts to mimic the behavior of another class without being
         its subclass may or may not be able to use the primitives of the original class.
         In general, if the instance variables read or written by a primitive have the
         same meanings and are in the same fields in both classes, the primitive will
         work.

         For certain frequently used 'special selectors', the compiler emits a
         send-special-selector bytecode instead of a send-message bytecode. Special
         selectors were created because they offer two advantages. First, code which
         sends special selectors compiles into fewer bytes than normal. Second, for
         some pairs of receiver classes and special selectors, the interpreter jumps
         directly to a primitive routine without looking up the method in the class,
         and the just-in-time (JIT) compiler (if in use) may emit code to directly execute
+        the primitive. At least in the interpreter this is much faster than a normal
-        the primitive. At least in the interpeeter this is much faster than a normal
         message lookup. In both the interpreter and the JIT send-special-selector,
+        conditional branch pairs are short-circuited for the comparison selectors when
+        applied to SmallIntegers or Floats.
-        conditional branch pairs are short-circuited for the comparison selectors.

+        A selector which is a special selector solely in order to save space has
-        A selector which is a special selector solely in order to save space has a
         normal behavior. Methods whose selectors are special in order to
+        gain speed contain the comment, 'No Lookup'. When the virtual machine
-        gain speed contain the comment, 'No Lookup'. When the interpreter
         encounters a send-special-selector bytecode, it checks the class of the
         receiver and the selector. If the class-selector pair is a no-lookup pair,
         then the interpreter swiftly jumps to the routine which implements the
         corresponding primitive. (A special selector whose receiver is not of the
         right class to make a no-lookup pair, is looked up normally). The pairs are
         listed below. No-lookup methods contain a primitive number specification,
         <primitive: xx>, which is redundant. Since the method is not normally looked
         up, deleting the primitive number specification cannot prevent this
         primitive from running. If a no-lookup primitive fails, the method is looked
         up normally, and the expressions in it are executed.

         No Lookup pairs of (class, selector)

         SmallInteger and Float with any of      + - * /
         SmallInteger with any of                        \\ bitOr: bitShift: bitAnd: // @
         SmallInteger and Float with any of      = ~= > < >= <=
         Any class with                                          == ~~ class
         Point with either of                                    x y                             (interpreter only)
         BlockClosure with either of                      value value:    (interpreter only)
         "

         self error: 'comment only'!

Item was changed:
----- Method: Object class>>whatIsAPrimitive (in category 'documentation') -----
whatIsAPrimitive
         "Some messages in the system are responded to primitively. A primitive
+         response is performed directly by the virtual machine rather than by
+         evaluating expressions in a method. The methods for these messages
+         indicate the presence of a primitive response by including one of
+                <primitive: N>
+                <primitive: N error: errorCode>
+                <primitive: 'primitiveName' module: 'module name'>
+                <primitive: 'primitiveName' module: 'module name' error: errorCode>
+         before the first expression in the method.
-        response is performed directly by the interpreter rather than by evaluating
-        expressions in a method. The methods for these messages indicate the
-        presence of a primitive response by including <primitive: xx> before the
-        first expression in the method.

+        Primitives exist for several reasons. Certain basic or 'primitive' operations
+        cannot be performed in any other way. Smalltalk without primitives can
+        move values from one variable to another, but cannot add two SmallIntegers
+        together. Many methods for arithmetic and comparison between numbers
+        are primitives. Some primitives allow Smalltalk to communicate with I/O
+        devices such as the disk, the display, and the keyboard. Some primitives
+        exist only to make the system run faster; each does the same thing as a
+        certain Smalltalk method, and its implementation as a primitive is optional.
+
+        When the Smalltalk virtual machine begins to execute a method which
+        specifies a primitive response, it tries to perform the primitive action and to
+        return a result. If the routine in the virtual machine for this primitive is
+        successful, it will return a value and the expressions in the method will not
+        be evaluated. If the primitive routine is not successful, the primitive 'fails',
+        and the Smalltalk expressions in the method are executed instead. These
+        expressions are evaluated as though the primitive routine had not been called.
+
+        The Smalltalk code that is evaluated when a primitive fails usually anticipates
+        why that primitive might fail. If the primitive is optional, the expressions in the
+        method do exactly what the primitive would have done (See Number @). If the
+        primitive only works on certain classes of arguments, the Smalltalk code tries
+        to coerce the argument or appeals to a superclass to find a more general way
+        of doing the operation (see SmallInteger +). If the primitive is never supposed
+        to fail, the expressions signal an error (see e.g. SmallInteger asFloat).
+
-        Primitives exist for several reasons. Certain basic or 'primitive'
-        operations cannot be performed in any other way. Smalltalk without
-        primitives can move values from one variable to another, but cannot add two
-        SmallIntegers together. Many methods for arithmetic and comparison
-        between numbers are primitives. Some primitives allow Smalltalk to
-        communicate with I/O devices such as the disk, the display, and the keyboard.
-        Some primitives exist only to make the system run faster; each does the same
-        thing as a certain Smalltalk method, and its implementation as a primitive is
-        optional.
-
-        When the Smalltalk interpreter begins to execute a method which specifies a
-        primitive response, it tries to perform the primitive action and to return a
-        result. If the routine in the interpreter for this primitive is successful,
-        it will return a value and the expressions in the method will not be evaluated.
-        If the primitive routine is not successful, the primitive 'fails', and the
-        Smalltalk expressions in the method are executed instead. These
-        expressions are evaluated as though the primitive routine had not been
-        called.
-
-        The Smalltalk code that is evaluated when a primitive fails usually
-        anticipates why that primitive might fail. If the primitive is optional, the
-        expressions in the method do exactly what the primitive would have done (See
-        Number @). If the primitive only works on certain classes of arguments, the
-        Smalltalk code tries to coerce the argument or appeals to a superclass to find
-        a more general way of doing the operation (see SmallInteger +). If the
-        primitive is never supposed to fail, the expressions signal an error (see
-        SmallInteger asFloat).
-
         Each method that specifies a primitive has a comment in it. If the primitive is
         optional, the comment will say 'Optional'. An optional primitive that is not
+        implemented always fails, and the Smalltalk expressions do the work instead.
-        implemented always fails, and the Smalltalk expressions do the work
-        instead.

+        If a primitive is not optional, the comment will say, 'Essential'. If the primitive is
+        so required, the comment will say 'Do not override in a subclass'. Some methods
+        will have the comment, 'No Lookup'. See Object howToModifyPrimitives for an
+        explanation of special selectors which are not looked up.
-        If a primitive is not optional, the comment will say, 'Essential'. Some
-        methods will have the comment, 'No Lookup'. See Object
-        howToModifyPrimitives for an explanation of special selectors which are
-        not looked up.

+        The comments in the SmallInteger primitives say 'Fails if result is not a SmallInteger',
+        even though the implementor has the option to construct a LargePositiveInteger.
+        For further information on primitives, see the 'Primitive Methods' part of the
+        chapter on the formal specification of the virtual machine in
+        Smalltalk-80: The Language and its Implementation."
-        For the primitives for +, -, *, and bitShift: in SmallInteger, and truncated
-        in Float, the primitive constructs and returns a 16-bit
-        LargePositiveInteger when the result warrants it. Returning 16-bit
-        LargePositiveIntegers from these primitives instead of failing is
-        optional in the same sense that the LargePositiveInteger arithmetic
-        primitives are optional. The comments in the SmallInteger primitives say,
-        'Fails if result is not a SmallInteger', even though the implementor has the
-        option to construct a LargePositiveInteger. For further information on
-        primitives, see the 'Primitive Methods' part of the chapter on the formal
-        specification of the interpreter in the Smalltalk book."

         self error: 'comment only'!

Carpe Squeak!

David T. Lewis

Re: self error: 'comment only' (was: The Trunk: Kernel-eem.1316.mcz)

On Mon, Mar 16, 2020 at 07:04:29PM +0000, Thiede, Christoph wrote:
> I really appreciate elaborate documentation comments like this. However,
> is it really necessary and seasonable to store them in methods whose only
> purpose is to hold a comment? IMHO, this is a quite abusive way to declare
> methods. Why can't we put this into class comments?
>

Necessary? No, there are lots of other places in which the documentation
could be stored. But it is nice to have it easily available when reading
class Object and trying to figure out how an "object" actually works.

Reasonable? Yes. Primitive calls apply to all objects, and it it not
intuitively obvious how they work. Documenting them on the class side
of Object is a reasonable thing to do.

Why can't we put this into class comments? It would not be reasonable to
put information like this in the class comment for Object. That would turn
the class comment into a mess, and it is important for class comments to
be clear and focused.

There are lots ways to provide documentation for a system, and most of
them either don't work or don't get maintained. But it is nice when the
documentation for a live, changing, system remain useful and relevant
for years and even decades. If you look at the method history for these
methods, you will see that it dates back to the earliest days of Squeak,
before the introduction of method time stamps with author initials.

These documentation methods are good and useful, and they explain a
not-so-obvious aspect of how objects behave. Read them and be happy :-)

Dave

>
> Best,
>
> Christoph
>
> ________________________________
> Von: Squeak-dev <[hidden email]> im Auftrag von [hidden email] <[hidden email]>
> Gesendet: Mittwoch, 11. M?rz 2020 21:03 Uhr
> An: [hidden email]; [hidden email]
> Betreff: [squeak-dev] The Trunk: Kernel-eem.1316.mcz
>
> Eliot Miranda uploaded a new version of Kernel to project The Trunk:
> http://source.squeak.org/trunk/Kernel-eem.1316.mcz
>
> ==================== Summary ====================
>
> Name: Kernel-eem.1316
> Author: eem
> Time: 11 March 2020, 1:02:37.986482 pm
> UUID: daa453eb-09f1-446b-bc64-6f6c0298daf2
> Ancestors: Kernel-nice.1315
>
> Improve Object class-side documentation for primtiives.
>
> =============== Diff against Kernel-nice.1315 ===============
>
> Item was changed:
> ----- Method: Object class>>howToModifyPrimitives (in category 'documentation') -----
> howToModifyPrimitives
> "You are allowed to write methods which specify primitives, but please use
> caution. If you make a subclass of a class which contains a primitive method,
> the subclass inherits the primitive. The message which is implemented
> primitively may be overridden in the subclass (E.g., see at:put: in String's
> subclass Symbol). The primitive behavior can be invoked using super (see
> Symbol string:).
>
> A class which attempts to mimic the behavior of another class without being
> its subclass may or may not be able to use the primitives of the original class.
> In general, if the instance variables read or written by a primitive have the
> same meanings and are in the same fields in both classes, the primitive will
> work.
>
> For certain frequently used 'special selectors', the compiler emits a
> send-special-selector bytecode instead of a send-message bytecode. Special
> selectors were created because they offer two advantages. First, code which
> sends special selectors compiles into fewer bytes than normal. Second, for
> some pairs of receiver classes and special selectors, the interpreter jumps
> directly to a primitive routine without looking up the method in the class,
> and the just-in-time (JIT) compiler (if in use) may emit code to directly execute
> + the primitive. At least in the interpreter this is much faster than a normal
> - the primitive. At least in the interpeeter this is much faster than a normal
> message lookup. In both the interpreter and the JIT send-special-selector,
> + conditional branch pairs are short-circuited for the comparison selectors when
> + applied to SmallIntegers or Floats.
> - conditional branch pairs are short-circuited for the comparison selectors.
>
> + A selector which is a special selector solely in order to save space has
> - A selector which is a special selector solely in order to save space has a
> normal behavior. Methods whose selectors are special in order to
> + gain speed contain the comment, 'No Lookup'. When the virtual machine
> - gain speed contain the comment, 'No Lookup'. When the interpreter
> encounters a send-special-selector bytecode, it checks the class of the
> receiver and the selector. If the class-selector pair is a no-lookup pair,
> then the interpreter swiftly jumps to the routine which implements the
> corresponding primitive. (A special selector whose receiver is not of the
> right class to make a no-lookup pair, is looked up normally). The pairs are
> listed below. No-lookup methods contain a primitive number specification,
> <primitive: xx>, which is redundant. Since the method is not normally looked
> up, deleting the primitive number specification cannot prevent this
> primitive from running. If a no-lookup primitive fails, the method is looked
> up normally, and the expressions in it are executed.
>
> No Lookup pairs of (class, selector)
>
> SmallInteger and Float with any of + - * /
> SmallInteger with any of \\ bitOr: bitShift: bitAnd: // @
> SmallInteger and Float with any of = ~= > < >= <=
> Any class with == ~~ class
> Point with either of x y (interpreter only)
> BlockClosure with either of value value: (interpreter only)
> "
>
> self error: 'comment only'!
>
> Item was changed:
> ----- Method: Object class>>whatIsAPrimitive (in category 'documentation') -----
> whatIsAPrimitive
> "Some messages in the system are responded to primitively. A primitive
> + response is performed directly by the virtual machine rather than by
> + evaluating expressions in a method. The methods for these messages
> + indicate the presence of a primitive response by including one of
> + <primitive: N>
> + <primitive: N error: errorCode>
> + <primitive: 'primitiveName' module: 'module name'>
> + <primitive: 'primitiveName' module: 'module name' error: errorCode>
> + before the first expression in the method.
> - response is performed directly by the interpreter rather than by evaluating
> - expressions in a method. The methods for these messages indicate the
> - presence of a primitive response by including <primitive: xx> before the
> - first expression in the method.
>
> + Primitives exist for several reasons. Certain basic or 'primitive' operations
> + cannot be performed in any other way. Smalltalk without primitives can
> + move values from one variable to another, but cannot add two SmallIntegers
> + together. Many methods for arithmetic and comparison between numbers
> + are primitives. Some primitives allow Smalltalk to communicate with I/O
> + devices such as the disk, the display, and the keyboard. Some primitives
> + exist only to make the system run faster; each does the same thing as a
> + certain Smalltalk method, and its implementation as a primitive is optional.
> +
> + When the Smalltalk virtual machine begins to execute a method which
> + specifies a primitive response, it tries to perform the primitive action and to
> + return a result. If the routine in the virtual machine for this primitive is
> + successful, it will return a value and the expressions in the method will not
> + be evaluated. If the primitive routine is not successful, the primitive 'fails',
> + and the Smalltalk expressions in the method are executed instead. These
> + expressions are evaluated as though the primitive routine had not been called.
> +
> + The Smalltalk code that is evaluated when a primitive fails usually anticipates
> + why that primitive might fail. If the primitive is optional, the expressions in the
> + method do exactly what the primitive would have done (See Number @). If the
> + primitive only works on certain classes of arguments, the Smalltalk code tries
> + to coerce the argument or appeals to a superclass to find a more general way
> + of doing the operation (see SmallInteger +). If the primitive is never supposed
> + to fail, the expressions signal an error (see e.g. SmallInteger asFloat).
> +
> - Primitives exist for several reasons. Certain basic or 'primitive'
> - operations cannot be performed in any other way. Smalltalk without
> - primitives can move values from one variable to another, but cannot add two
> - SmallIntegers together. Many methods for arithmetic and comparison
> - between numbers are primitives. Some primitives allow Smalltalk to
> - communicate with I/O devices such as the disk, the display, and the keyboard.
> - Some primitives exist only to make the system run faster; each does the same
> - thing as a certain Smalltalk method, and its implementation as a primitive is
> - optional.
> -
> - When the Smalltalk interpreter begins to execute a method which specifies a
> - primitive response, it tries to perform the primitive action and to return a
> - result. If the routine in the interpreter for this primitive is successful,
> - it will return a value and the expressions in the method will not be evaluated.
> - If the primitive routine is not successful, the primitive 'fails', and the
> - Smalltalk expressions in the method are executed instead. These
> - expressions are evaluated as though the primitive routine had not been
> - called.
> -
> - The Smalltalk code that is evaluated when a primitive fails usually
> - anticipates why that primitive might fail. If the primitive is optional, the
> - expressions in the method do exactly what the primitive would have done (See
> - Number @). If the primitive only works on certain classes of arguments, the
> - Smalltalk code tries to coerce the argument or appeals to a superclass to find
> - a more general way of doing the operation (see SmallInteger +). If the
> - primitive is never supposed to fail, the expressions signal an error (see
> - SmallInteger asFloat).
> -
> Each method that specifies a primitive has a comment in it. If the primitive is
> optional, the comment will say 'Optional'. An optional primitive that is not
> + implemented always fails, and the Smalltalk expressions do the work instead.
> - implemented always fails, and the Smalltalk expressions do the work
> - instead.
>
> + If a primitive is not optional, the comment will say, 'Essential'. If the primitive is
> + so required, the comment will say 'Do not override in a subclass'. Some methods
> + will have the comment, 'No Lookup'. See Object howToModifyPrimitives for an
> + explanation of special selectors which are not looked up.
> - If a primitive is not optional, the comment will say, 'Essential'. Some
> - methods will have the comment, 'No Lookup'. See Object
> - howToModifyPrimitives for an explanation of special selectors which are
> - not looked up.
>
> + The comments in the SmallInteger primitives say 'Fails if result is not a SmallInteger',
> + even though the implementor has the option to construct a LargePositiveInteger.
> + For further information on primitives, see the 'Primitive Methods' part of the
> + chapter on the formal specification of the virtual machine in
> + Smalltalk-80: The Language and its Implementation."
> - For the primitives for +, -, *, and bitShift: in SmallInteger, and truncated
> - in Float, the primitive constructs and returns a 16-bit
> - LargePositiveInteger when the result warrants it. Returning 16-bit
> - LargePositiveIntegers from these primitives instead of failing is
> - optional in the same sense that the LargePositiveInteger arithmetic
> - primitives are optional. The comments in the SmallInteger primitives say,
> - 'Fails if result is not a SmallInteger', even though the implementor has the
> - option to construct a LargePositiveInteger. For further information on
> - primitives, see the 'Primitive Methods' part of the chapter on the formal
> - specification of the interpreter in the Smalltalk book."
>
> self error: 'comment only'!
>
>

timrowledge

Re: self error: 'comment only' (was: The Trunk: Kernel-eem.1316.mcz)

> On 2020-03-16, at 7:57 PM, David T. Lewis <[hidden email]> wrote:
>
> These documentation methods are good and useful, and they explain a
> not-so-obvious aspect of how objects behave. Read them and be happy :-)

We *could* consider making them appear in the HelpBrowser, or indeed gradually migrating to use of that for such stuff. Since we have it anyway...

tim
--
tim Rowledge; [hidden email]; http://www.rowledge.org/tim
"Mr. Worf, scan that ship." "Aye aye, Captain... 300 DPI?

K K Subbu

Re: self error: 'comment only'

On 17/03/20 8:55 AM, tim Rowledge wrote:
>> On 2020-03-16, at 7:57 PM, David T. Lewis<[hidden email]>
>> wrote:
>>
>> These documentation methods are good and useful, and they explain
>> a not-so-obvious aspect of how objects behave. Read them and be
>> happy:-)
> We*could* consider making them appear in the HelpBrowser, or indeed
> gradually migrating to use of that for such stuff. Since we have it
> anyway...

It already does - Browser -> Object -> show all comments -> class side

Perhaps it could be made simpler. "show all comments" could be renamed
to just "help" and lead to instance/class side depending on its switch.

BTW, would it be better to display "Object class", "ProtoObject class"
etc in the class list pane when displaying class side methods?
Currently, one has to look below to ensure that the right instance/class
switch is set.

Regards .. Subbu

Christoph Thiede

Re: self error: 'comment only' (was: The Trunk: Kernel-eem.1316.mcz)

In reply to this post by timrowledge

Hi all,

of course, I *am* happy about these comments! I see your point not to move them into a far location where you cannot find it quickly. @tim, there are rough plans to make Squeak modular (at least I would appreciate this concern). This should also include the ability to unload help packages, which would be okay if you're not interested to learn how a Transcript works, but it is a fair point that the description of the system should be stored side-by-side to its implementation.

However, we are talking basically about two comments only at the moment. Couldn't we just move the contents of #whatIsAPrimitive and #howToModifyPrimitives into #primitiveFailed:? Then we would not have these useless method stubs on class side, and even better, the chance for any Squeak Surfers to come across this stuff will be increased. I claim that almost every reader of this documentation comes from any primitive method that states "See Object documentation whatIsAPrimitive." Via debugging/iMplementors browsing, much more people will read any stuff that is located along the caller stack.

Best,

Christoph

Von: Squeak-dev <[hidden email]> im Auftrag von tim Rowledge <[hidden email]>
Gesendet: Dienstag, 17. März 2020 04:25:28
An: The general-purpose Squeak developers list
Betreff: Re: [squeak-dev] self error: 'comment only' (was: The Trunk: Kernel-eem.1316.mcz)

Carpe Squeak!

timrowledge

Re: self error: 'comment only' (was: The Trunk: Kernel-eem.1316.mcz)

> On 2020-03-17, at 12:02 PM, Thiede, Christoph <[hidden email]> wrote:
> @tim, there are rough plans to make Squeak modular
Yeah; I'm one of the people that started trying to do that around 25 years ago..

tim
--
tim Rowledge; [hidden email]; http://www.rowledge.org/tim
Maniac: An early computer built by nuts...

K K Subbu

Re: self error: 'comment only'

In reply to this post by Christoph Thiede

On 18/03/20 12:32 AM, Thiede, Christoph wrote:
> However, we are talking basically about two comments only at the moment.
> Couldn't we just move the contents of #whatIsAPrimitive and
> #howToModifyPrimitives into #primitiveFailed:?

I see your point about not abusing method entries for holding comments.
I also understand Dave's comments about Object class not being the right
place for such comments. The logical place is not primitiveFailed: but
CompiledMethod>>primitive. After all, primitives are associated only
with compiled method objects not all objects.

For now, The help text methods could be left in place but modified to
point to the new location. When all references to these methods are
removed, the methods themselves may be removed.

Regards .. Subbu

Tobias Pape

Re: self error: 'comment only' (was: The Trunk: Kernel-eem.1316.mcz)

In reply to this post by Christoph Thiede

hi

> On 17.03.2020, at 20:02, Thiede, Christoph <[hidden email]> wrote:
>
> Hi all,
>
> of course, I *am* happy about these comments! I see your point not to move them into a far location where you cannot find it quickly. @tim, there are rough plans to make Squeak modular (at least I would appreciate this concern). This should also include the ability to unload help packages, which would be okay if you're not interested to learn how a Transcript works, but it is a fair point that the description of the system should be stored side-by-side to its implementation.
>
> However, we are talking basically about two comments only at the moment. Couldn't we just move the contents of #whatIsAPrimitive and #howToModifyPrimitives into #primitiveFailed:? Then we would not have these useless method stubs on class side, and even better, the chance for any Squeak Surfers to come across this stuff will be increased. I claim that almost every reader of this documentation comes from any primitive method that states "See Object documentation whatIsAPrimitive." Via debugging/iMplementors browsing, much more people will read any stuff that is located along the caller stack.
>

I find the documentation-only methods have a kind of charm to them.
I see no real need to merge them somewhere else.
It is more like: If the Class comment doesn't fit what you want to say, put it in a method.
I don't think changing the current state would improve space consumption, speed, discoverability, or so.

Let's keep it :)

Best regards
-Tobias

> Best,
> Christoph
> Von: Squeak-dev <[hidden email]> im Auftrag von tim Rowledge <[hidden email]>
> Gesendet: Dienstag, 17. März 2020 04:25:28
> An: The general-purpose Squeak developers list
> Betreff: Re: [squeak-dev] self error: 'comment only' (was: The Trunk: Kernel-eem.1316.mcz)
>
>
>
> > On 2020-03-16, at 7:57 PM, David T. Lewis <[hidden email]> wrote:
> >
> > These documentation methods are good and useful, and they explain a
> > not-so-obvious aspect of how objects behave. Read them and be happy :-)
>
> We *could* consider making them appear in the HelpBrowser, or indeed gradually migrating to use of that for such stuff. Since we have it anyway...
>
> tim

Eliot Miranda-2

Re: self error: 'comment only' (was: The Trunk: Kernel-eem.1316.mcz)

In reply to this post by timrowledge

> On Mar 16, 2020, at 8:25 PM, tim Rowledge <[hidden email]> wrote:
>
>
>> On 2020-03-16, at 7:57 PM, David T. Lewis <[hidden email]> wrote:
>>
>> These documentation methods are good and useful, and they explain a
>> not-so-obvious aspect of how objects behave. Read them and be happy :-)
>
> We *could* consider making them appear in the HelpBrowser, or indeed gradually migrating to use of that for such stuff. Since we have it anyway...

+1000. I would also try and include selected class comments. Or at least make the help browser able to direct one to them.

> tim
> --
> tim Rowledge; [hidden email]; http://www.rowledge.org/tim
> "Mr. Worf, scan that ship." "Aye aye, Captain... 300 DPI?
>
>
>

David T. Lewis

Re: self error: 'comment only' (was: The Trunk: Kernel-eem.1316.mcz)

In reply to this post by timrowledge

On Mon, Mar 16, 2020 at 08:25:28PM -0700, tim Rowledge wrote:
>
>
> > On 2020-03-16, at 7:57 PM, David T. Lewis <[hidden email]> wrote:
> >
> > These documentation methods are good and useful, and they explain a
> > not-so-obvious aspect of how objects behave. Read them and be happy :-)
>
> We *could* consider making them appear in the HelpBrowser, or indeed gradually migrating to use of that for such stuff. Since we have it anyway...
>

Yes, somebody could do that, and no complaints from me if they do.
Meanwhile those documentation methods are useful, and I am happy.

Dave

David T. Lewis

Re: self error: 'comment only' (was: The Trunk: Kernel-eem.1316.mcz)

On Fri, Mar 20, 2020 at 11:48:33PM -0400, David T. Lewis wrote:

> On Mon, Mar 16, 2020 at 08:25:28PM -0700, tim Rowledge wrote:
> >
> >
> > > On 2020-03-16, at 7:57 PM, David T. Lewis <[hidden email]> wrote:
> > >
> > > These documentation methods are good and useful, and they explain a
> > > not-so-obvious aspect of how objects behave. Read them and be happy :-)
> >
> > We *could* consider making them appear in the HelpBrowser, or indeed gradually migrating to use of that for such stuff. Since we have it anyway...
> >
>
> Yes, somebody could do that, and no complaints from me if they do.
> Meanwhile those documentation methods are useful, and I am happy.
>

Ugh, sorry. That was an unsent message that I meant to send to my trash
can, and I accidentally sent to the list.

Regardless, I do like Tim's suggestion of adding them to the help browser.
Aside from that, sorry for the noise.

Back to cleaning out my mailbox,
Dave

timrowledge

Re: self error: 'comment only'

In reply to this post by K K Subbu

> On 2020-03-17, at 12:56 AM, K K Subbu <[hidden email]> wrote:
>
>>
>
> It already does - Browser -> Object -> show all comments -> class side

Hunh. Never noticed that before; which is an example of a mix of "long-habit making new stuff almost invisible" and "too long menu disease".

I think it does the wrong thing though; a more consistent approach would be to have the HelpBrowser page with that info installed in the HB that opens when you ask for Help. Removes a then-pointless menu entry and make the HB more useful.

A related issue is the lack of actually useful class comments - and indeed the fact that class comments are a small part of the total need to explanations. If we were to make really thorough use of the HB to document things one might argue that individual class comments would become irrelevant. Certainly the tragically simplistic approach I've seen (I think it was called javadoc?) that simply gathers up every comment and tries to pretend that it makes actual documentation is not one to copy.

Making good doc and good tools to make that easily available and easy to keep up to date is hard work. I think we have a lot of decent starting points though. We can, for example fetch swiki pages fairly easily, which would be a great thing to improve for major doc items. They can be updated easily by a wide community, which is hopeful. A downside is the requirement to be online, which means we might want to work out a way of having some basic doc held in local space (probably best is the sources file since we usually at least have that) as well. And being better at parsing the content of swiki pages would be nice; or perhaps extending the swiki system to be able to return data in a more digestible form when the requestor is an HB?

tim
--
tim Rowledge; [hidden email]; http://www.rowledge.org/tim
<-------- The information went data way -------->

David T. Lewis

Re: self error: 'comment only'

On Sat, Mar 21, 2020 at 11:21:39AM -0700, tim Rowledge wrote:

>
>
> > On 2020-03-17, at 12:56 AM, K K Subbu <[hidden email]> wrote:
> >
> >>
> >
> > It already does - Browser -> Object -> show all comments -> class side
>
> Hunh. Never noticed that before; which is an example of a mix of "long-habit making new stuff almost invisible" and "too long menu disease".
>

I overlooked this too. Thanks Subbu!

> I think it does the wrong thing though; a more consistent approach would be to have the HelpBrowser page with that info installed in the HB that opens when you ask for Help. Removes a then-pointless menu entry and make the HB more useful.
>
> A related issue is the lack of actually useful class comments - and indeed the fact that class comments are a small part of the total need to explanations. If we were to make really thorough use of the HB to document things one might argue that individual class comments would become irrelevant. Certainly the tragically simplistic approach I've seen (I think it was called javadoc?) that simply gathers up every comment and tries to pretend that it makes actual documentation is not one to copy.
>

Actually, javadoc can do a very nice job of generating documentation
if someone has taken the time to write good comments in the first
place. Not unlike the situation in Squeak.

Dave

> Making good doc and good tools to make that easily available and easy to keep up to date is hard work. I think we have a lot of decent starting points though. We can, for example fetch swiki pages fairly easily, which would be a great thing to improve for major doc items. They can be updated easily by a wide community, which is hopeful. A downside is the requirement to be online, which means we might want to work out a way of having some basic doc held in local space (probably best is the sources file since we usually at least have that) as well. And being better at parsing the content of swiki pages would be nice; or perhaps extending the swiki system to be able to return data in a more digestible form when the requestor is an HB?
>
> tim
> --
> tim Rowledge; [hidden email]; http://www.rowledge.org/tim
> <-------- The information went data way -------->
>
>
>

Christoph Thiede

Re: self error: 'comment only'

> Actually, javadoc can do a very nice job of generating documentation if someone has taken the time to write good comments in the first place. Not unlike the situation in Squeak.

I think I don't like documentation generation. This is a classical scenario of creating a representation that lacks liveness and needs to be kept in sync, making it impossible to edit the generated document, unless the synchronization is implemented as a bidirectional process. Especially in Squeak, we should be very careful to create such derived representations. Ideally, we should also never copy documentation stuff into the Swiki, but implement a hook/special syntax there that allows citing it directly from the Swiki server's image.

Best,

Christoph

Von: Squeak-dev <[hidden email]> im Auftrag von David T. Lewis <[hidden email]>
Gesendet: Samstag, 21. März 2020 20:03:36
An: The general-purpose Squeak developers list
Betreff: Re: [squeak-dev] self error: 'comment only'

On Sat, Mar 21, 2020 at 11:21:39AM -0700, tim Rowledge wrote:
>
>
> > On 2020-03-17, at 12:56 AM, K K Subbu <[hidden email]> wrote:
> >
> >>
> >
> > It already does - Browser -> Object -> show all comments -> class side
>
> Hunh. Never noticed that before; which is an example of a mix of "long-habit making new stuff almost invisible" and "too long menu disease".
>

I overlooked this too. Thanks Subbu!

> I think it does the wrong thing though; a more consistent approach would be to have the HelpBrowser page with that info installed in the HB that opens when you ask for Help. Removes a then-pointless menu entry and make the HB more useful.
>
> A related issue is the lack of actually useful class comments - and indeed the fact that class comments are a small part of the total need to explanations. If we were to make really thorough use of the HB to document things one might argue that individual class comments would become irrelevant. Certainly the tragically simplistic approach I've seen (I think it was called javadoc?) that simply gathers up every comment and tries to pretend that it makes actual documentation is not one to copy.
>

Actually, javadoc can do a very nice job of generating documentation
if someone has taken the time to write good comments in the first
place. Not unlike the situation in Squeak.

Dave

> Making good doc and good tools to make that easily available and easy to keep up to date is hard work. I think we have a lot of decent starting points though. We can, for example fetch swiki pages fairly easily, which would be a great thing to improve for major doc items. They can be updated easily by a wide community, which is hopeful. A downside is the requirement to be online, which means we might want to work out a way of having some basic doc held in local space (probably best is the sources file since we usually at least have that) as well. And being better at parsing the content of swiki pages would be nice; or perhaps extending the swiki system to be able to return data in a more digestible form when the requestor is an HB?
>
> tim
> --
> tim Rowledge; [hidden email]; http://www.rowledge.org/tim
> <-------- The information went data way -------->
>
>
>

Carpe Squeak!

timrowledge

Re: self error: 'comment only'

> On 2020-03-21, at 12:11 PM, Thiede, Christoph <[hidden email]> wrote:
>
> > Actually, javadoc can do a very nice job of generating documentation if someone has taken the time to write good comments in the first place. Not unlike the situation in Squeak.
>
> I think I don't like documentation generation.

The problem is always, at the end, having some useful content. A level up from that is having said useful content well organised. I'm sure it's possible to make a javadoc thing that assembles stuff, and surely it must be possible to tag it to aid organisation. Does it do that? No idea; I don't go near java.

> . Ideally, we should also never copy documentation stuff into the Swiki, but implement a hook/special syntax there that allows citing it directly from the Swiki server's image.

Yeah, probably. I'm sure we could either parse the html the swiki returns a bit better (after all, we used to have a not too terrible web browser and it's not like the swiki produces complex 'modern' web pages that rely on implausible numbers of poorly written and badly used frameworks residing on a gazillion different sites ... oh, wait, am I ranting again?) or we could possibly make a swiki that provides more easily digestible pseudo-html (or maybe sometihng like markdown, or even, since the swiki is a sort of markup language just the raw text) on suitable request.

Obviously, the main issue is still content. And not all the swiki needs to be handled, after all; just pages that are tagged as part of the help doc system.

tim
--
tim Rowledge; [hidden email]; http://www.rowledge.org/tim
Security announcement - as of next week, passwords will be entered in Morse code.

David T. Lewis

Live documentation rendering (was: self error: 'comment only')

In reply to this post by Christoph Thiede

Hmmm.... good points Christoph.

I'm sure this must have been done before, but how about a Seaside
application with an image keeping itself up-to-date with the trunk
update stream, and with Seaside rendering something similar to the
"show all comments" browser that Subbu reminded us about?

I recall an early Seaside demo that implemented Smalltalk browsing,
so it might be something similar to that browser but more focused
on rendering the documentation (comments) than the code.

I suppose that in this case, "editing the document" would amount
to putting some new or improved comments into trunk.

I think we already have (or had???) some way to embed href links
in Squeak comments, so possibly that would be a way to provide
links to more extensive documentation on the swiki. This has not
been very useful in the image (once apon a time we had the embedded
Whisker browser, but those days are gone). But maybe that sort
of linkage might be more useful if comments were being rendered
from a Seaside app.

Something like this might be a nice thing to have running on our
Rackspace servers and linked to squeak.org.

Dave

On Sat, Mar 21, 2020 at 07:11:08PM +0000, Thiede, Christoph wrote:

> > Actually, javadoc can do a very nice job of generating documentation if someone has taken the time to write good comments in the first place. Not unlike the situation in Squeak.
>
> I think I don't like documentation generation. This is a classical scenario of creating a representation that lacks liveness and needs to be kept in sync, making it impossible to edit the generated document, unless the synchronization is implemented as a bidirectional process. Especially in Squeak, we should be very careful to create such derived representations. Ideally, we should also never copy documentation stuff into the Swiki, but implement a hook/special syntax there that allows citing it directly from the Swiki server's image.
>
> Best,
> Christoph
>
> ________________________________
> Von: Squeak-dev <[hidden email]> im Auftrag von David T. Lewis <[hidden email]>
> Gesendet: Samstag, 21. M?rz 2020 20:03:36
> An: The general-purpose Squeak developers list
> Betreff: Re: [squeak-dev] self error: 'comment only'
>
> On Sat, Mar 21, 2020 at 11:21:39AM -0700, tim Rowledge wrote:
> >
> >
> > > On 2020-03-17, at 12:56 AM, K K Subbu <[hidden email]> wrote:
> > >
> > >>
> > >
> > > It already does - Browser -> Object -> show all comments -> class side
> >
> > Hunh. Never noticed that before; which is an example of a mix of "long-habit making new stuff almost invisible" and "too long menu disease".
> >
>
> I overlooked this too. Thanks Subbu!
>
>
> > I think it does the wrong thing though; a more consistent approach would be to have the HelpBrowser page with that info installed in the HB that opens when you ask for Help. Removes a then-pointless menu entry and make the HB more useful.
> >
> > A related issue is the lack of actually useful class comments - and indeed the fact that class comments are a small part of the total need to explanations. If we were to make really thorough use of the HB to document things one might argue that individual class comments would become irrelevant. Certainly the tragically simplistic approach I've seen (I think it was called javadoc?) that simply gathers up every comment and tries to pretend that it makes actual documentation is not one to copy.
> >
>
> Actually, javadoc can do a very nice job of generating documentation
> if someone has taken the time to write good comments in the first
> place. Not unlike the situation in Squeak.
>
> Dave
>
>
> > Making good doc and good tools to make that easily available and easy to keep up to date is hard work. I think we have a lot of decent starting points though. We can, for example fetch swiki pages fairly easily, which would be a great thing to improve for major doc items. They can be updated easily by a wide community, which is hopeful. A downside is the requirement to be online, which means we might want to work out a way of having some basic doc held in local space (probably best is the sources file since we usually at least have that) as well. And being better at parsing the content of swiki pages would be nice; or perhaps extending the swiki system to be able to return data in a more digestible form when the requestor is an HB?
> >
> > tim
> > --
> > tim Rowledge; [hidden email]; http://www.rowledge.org/tim
> > <-------- The information went data way -------->
> >
> >
> >
>

K K Subbu

Re: self error: 'comment only'

In reply to this post by timrowledge

On 21/03/20 11:51 PM, tim Rowledge wrote:
> Making good doc and good tools to make that easily available and easy
> to keep up to date is hard work. I think we have a lot of decent
> starting points though. We can, for example fetch swiki pages fairly
> easily, which would be a great thing to improve for major doc items.

Separating document from code has never worked out well in the past.
Code is for machine to execute and no amount of comments embedded in
code will replace a proper narrative guide intended for programmers.
When reading such comments, I tend to miss the forest for the trees.

Most documents that have endured in the past (The C Programming book by
K&R, anyone?) fall primarily into two types: guides and references. The
guides are compact narrations intended for on-boarding programmers. The
references are comprehensive dictionaries intended for lookup by
experienced programmers. One could refine these into more sub-types
(like tutorials, cookbooks etc), but these two are essential and
sufficient (for small self-supported groups like us).

Examples of the first kind are - Introduction to Morphic, Back to the
Future, Etoys Quick Guides. These are difficult, but not impossible, to
get off the ground and need support from the code (e.g. for active
essays). Whenever a new concept or design is introduced in a release, a
chapter/section/glossary should be added to it (even if empty). In
Squeak, it is easy to write small narrations as active essays and update
them every Squeak release. We do this already in bits and pieces but we
need to put all the wood behind a single arrow.

The class comments and terse guide belong to the second category. They
can serve to refresh memory but are not substitutes for a proper
narrative. Comments like whatIsAPrimitive should be merged into a
narrative flow rather than stick out in isolation.

While I use Squeak swiki, I feel it is inferior to an in-image guide.
Swikis don't let me switch into browsers or inspectors. We could write
narrative texts as Help topics and books and use a in-image swiki server
to export to HTML on the fly (or produce PDFs for offline reading).
Topics can be patched with changesets just like code. An in-image guide
and swiki server may add an extra 2-3MB but it would take less effort
overall in keeping them in sync with code. Experienced developers can
always strip them out from production images if size becomes an issue.

I am not in favor of placing guides outside Squeak image and using
in-image PDF or WWW browser to read them. Browser specifications have
become too baroque and complex for any sane implementation. An in-image
browser would result in a huge code bloat and divert efforts away from
the core product.

Regards .. Subbu

David T. Lewis

Re: self error: 'comment only'

There is some very good guidance in this note. Thanks Subbu.

Dave

On Sun, Mar 22, 2020 at 03:06:55PM +0530, K K Subbu wrote:

> On 21/03/20 11:51 PM, tim Rowledge wrote:
> >Making good doc and good tools to make that easily available and easy
> >to keep up to date is hard work. I think we have a lot of decent
> >starting points though. We can, for example fetch swiki pages fairly
> >easily, which would be a great thing to improve for major doc items.
>
> Separating document from code has never worked out well in the past.
> Code is for machine to execute and no amount of comments embedded in
> code will replace a proper narrative guide intended for programmers.
> When reading such comments, I tend to miss the forest for the trees.
>
> Most documents that have endured in the past (The C Programming book by
> K&R, anyone?) fall primarily into two types: guides and references. The
> guides are compact narrations intended for on-boarding programmers. The
> references are comprehensive dictionaries intended for lookup by
> experienced programmers. One could refine these into more sub-types
> (like tutorials, cookbooks etc), but these two are essential and
> sufficient (for small self-supported groups like us).
>
> Examples of the first kind are - Introduction to Morphic, Back to the
> Future, Etoys Quick Guides. These are difficult, but not impossible, to
> get off the ground and need support from the code (e.g. for active
> essays). Whenever a new concept or design is introduced in a release, a
> chapter/section/glossary should be added to it (even if empty). In
> Squeak, it is easy to write small narrations as active essays and update
> them every Squeak release. We do this already in bits and pieces but we
> need to put all the wood behind a single arrow.
>
> The class comments and terse guide belong to the second category. They
> can serve to refresh memory but are not substitutes for a proper
> narrative. Comments like whatIsAPrimitive should be merged into a
> narrative flow rather than stick out in isolation.
>
> While I use Squeak swiki, I feel it is inferior to an in-image guide.
> Swikis don't let me switch into browsers or inspectors. We could write
> narrative texts as Help topics and books and use a in-image swiki server
> to export to HTML on the fly (or produce PDFs for offline reading).
> Topics can be patched with changesets just like code. An in-image guide
> and swiki server may add an extra 2-3MB but it would take less effort
> overall in keeping them in sync with code. Experienced developers can
> always strip them out from production images if size becomes an issue.
>
> I am not in favor of placing guides outside Squeak image and using
> in-image PDF or WWW browser to read them. Browser specifications have
> become too baroque and complex for any sane implementation. An in-image
> browser would result in a huge code bloat and divert efforts away from
> the core product.
>
> Regards .. Subbu
>

Squeak - Dev mailing list

Re: Live documentation rendering (was: self error:    'comment only')

In reply to this post by David T. Lewis

SeasideDoc may be of use to you here.

http://squeaksource.com/@98wPRO3xoqcWHC8c/NtvPSZ9c

---- On Sat, 21 Mar 2020 17:34:10 -0400 [hidden email] wrote ----

Hmmm.... good points Christoph.

I'm sure this must have been done before, but how about a Seaside
application with an image keeping itself up-to-date with the trunk
update stream, and with Seaside rendering something similar to the
"show all comments" browser that Subbu reminded us about?

I recall an early Seaside demo that implemented Smalltalk browsing,
so it might be something similar to that browser but more focused
on rendering the documentation (comments) than the code.

I suppose that in this case, "editing the document" would amount
to putting some new or improved comments into trunk.

I think we already have (or had???) some way to embed href links
in Squeak comments, so possibly that would be a way to provide
links to more extensive documentation on the swiki. This has not
been very useful in the image (once apon a time we had the embedded
Whisker browser, but those days are gone). But maybe that sort
of linkage might be more useful if comments were being rendered
from a Seaside app.

Something like this might be a nice thing to have running on our
Rackspace servers and linked to squeak.org.

Dave

On Sat, Mar 21, 2020 at 07:11:08PM +0000, Thiede, Christoph wrote:

> > Actually, javadoc can do a very nice job of generating documentation if someone has taken the time to write good comments in the first place. Not unlike the situation in Squeak.
>
> I think I don't like documentation generation. This is a classical scenario of creating a representation that lacks liveness and needs to be kept in sync, making it impossible to edit the generated document, unless the synchronization is implemented as a bidirectional process. Especially in Squeak, we should be very careful to create such derived representations. Ideally, we should also never copy documentation stuff into the Swiki, but implement a hook/special syntax there that allows citing it directly from the Swiki server's image.
>
> Best,
> Christoph
>
> ________________________________
> Von: Squeak-dev <[hidden email]> im Auftrag von David T. Lewis <[hidden email]>
> Gesendet: Samstag, 21. M?rz 2020 20:03:36
> An: The general-purpose Squeak developers list
> Betreff: Re: [squeak-dev] self error: 'comment only'
>
> On Sat, Mar 21, 2020 at 11:21:39AM -0700, tim Rowledge wrote:
> >
> >
> > > On 2020-03-17, at 12:56 AM, K K Subbu <[hidden email]> wrote:
> > >
> > >>
> > >
> > > It already does - Browser -> Object -> show all comments -> class side
> >
> > Hunh. Never noticed that before; which is an example of a mix of "long-habit making new stuff almost invisible" and "too long menu disease".
> >
>
> I overlooked this too. Thanks Subbu!
>
>
> > I think it does the wrong thing though; a more consistent approach would be to have the HelpBrowser page with that info installed in the HB that opens when you ask for Help. Removes a then-pointless menu entry and make the HB more useful.
> >
> > A related issue is the lack of actually useful class comments - and indeed the fact that class comments are a small part of the total need to explanations. If we were to make really thorough use of the HB to document things one might argue that individual class comments would become irrelevant. Certainly the tragically simplistic approach I've seen (I think it was called javadoc?) that simply gathers up every comment and tries to pretend that it makes actual documentation is not one to copy.
> >
>
> Actually, javadoc can do a very nice job of generating documentation
> if someone has taken the time to write good comments in the first
> place. Not unlike the situation in Squeak.
>
> Dave
>
>
> > Making good doc and good tools to make that easily available and easy to keep up to date is hard work. I think we have a lot of decent starting points though. We can, for example fetch swiki pages fairly easily, which would be a great thing to improve for major doc items. They can be updated easily by a wide community, which is hopeful. A downside is the requirement to be online, which means we might want to work out a way of having some basic doc held in local space (probably best is the sources file since we usually at least have that) as well. And being better at parsing the content of swiki pages would be nice; or perhaps extending the swiki system to be able to return data in a more digestible form when the requestor is an HB?
> >
> > tim
> > --
> > tim Rowledge; [hidden email]; http://www.rowledge.org/tim
> > <-------- The information went data way -------->
> >
> >
> >
>

>

The Trunk: Kernel-eem.1316.mcz

The Trunk: Kernel-eem.1316.mcz

self error: 'comment only' (was: The Trunk: Kernel-eem.1316.mcz)

Re: self error: 'comment only' (was: The Trunk: Kernel-eem.1316.mcz)

Re: self error: 'comment only' (was: The Trunk: Kernel-eem.1316.mcz)

Re: self error: 'comment only'

Re: self error: 'comment only' (was: The Trunk: Kernel-eem.1316.mcz)

Re: self error: 'comment only' (was: The Trunk: Kernel-eem.1316.mcz)

Re: self error: 'comment only'

Re: self error: 'comment only' (was: The Trunk: Kernel-eem.1316.mcz)

Re: self error: 'comment only' (was: The Trunk: Kernel-eem.1316.mcz)

Re: self error: 'comment only' (was: The Trunk: Kernel-eem.1316.mcz)

Re: self error: 'comment only' (was: The Trunk: Kernel-eem.1316.mcz)

Re: self error: 'comment only'

Re: self error: 'comment only'

Re: self error: 'comment only'

Re: self error: 'comment only'

Live documentation rendering (was: self error: 'comment only')

Re: self error: 'comment only'

Re: self error: 'comment only'

Re: Live documentation rendering (was: self error:&nbsp;&nbsp;&nbsp;&nbsp;'comment only')

Re: Live documentation rendering (was: self error: 'comment only')