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'!