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