kernel: Review age-old code comments.

support/boot.js

@@ -64,8 +64,10 @@ define(['require', './brikz', './compatibility'], function (require, Brikz) {
     function RootBrik(brikz, st) {
         /* Smalltalk foundational objects */
 
-        /* SmalltalkRoot is the hidden root of the Amber hierarchy.
-         All objects including `Object` inherit from SmalltalkRoot */
+        /* SmalltalkRoot is the hidden root of the normal Amber hierarchy.
+          All objects including `ProtoObject` inherit from SmalltalkRoot.
+          Detached roots (eg. wrapped JS classes like Number or Date)
+          do not directly inherit from SmalltalkRoot, but employ a workaround.*/
         function SmalltalkRoot() {
         }
 
@@ -95,7 +97,7 @@ define(['require', './brikz', './compatibility'], function (require, Brikz) {
             enumerable: false, configurable: false, writable: false
         });
 
-        // Hidden root class of the system.
+        // Fake root class of the system.
         // Effective superclass of all classes created with `nil subclass: ...`.
         this.nilAsClass = {fn: SmalltalkRoot};
 
@@ -173,8 +175,6 @@ define(['require', './brikz', './compatibility'], function (require, Brikz) {
             return pair;
         };
 
-        /* Answer all method selectors based on dnu handlers */
-
         st.allSelectors = function () {
             return selectors;
         };
@@ -210,8 +210,8 @@ define(['require', './brikz', './compatibility'], function (require, Brikz) {
             return that;
         }
 
-        /* Add a package to the smalltalk.packages object, creating a new one if needed.
-         If pkgName is null or empty we return nil, which is an allowed package for a class.
+        /* Add a package to the system, creating a new one if needed.
+         If pkgName is null or empty we return nil.
          If package already exists we still update the properties of it. */
 
         st.addPackage = function (pkgName, properties) {
@@ -281,8 +281,8 @@ define(['require', './brikz', './compatibility'], function (require, Brikz) {
 
         /* Smalltalk class creation. A class is an instance of an automatically
          created metaclass object. Newly created classes (not their metaclass)
-         should be added to the smalltalk object, see smalltalk.addClass().
-         Superclass linking is *not* handled here, see smalltalk.init()  */
+         should be added to the system, see smalltalk.addClass().
+         Superclass linking is *not* handled here, see api.initialize()  */
 
         function klass(spec) {
             var setSuperClass = spec.superclass;
@@ -339,8 +339,8 @@ define(['require', './brikz', './compatibility'], function (require, Brikz) {
 
         this.wireKlass = wireKlass;
 
-        /* Add a class to the smalltalk object, creating a new one if needed.
-         A Package is lazily created if it does not exist with given name. */
+        /* Add a class to the system, creating a new one if needed.
+         A Package is lazily created if one with given name does not exist. */
 
         st.addClass = function (className, superclass, iVarNames, pkgName) {
             // While subclassing nil is allowed, it might be an error, so
@@ -407,7 +407,7 @@ define(['require', './brikz', './compatibility'], function (require, Brikz) {
         }
 
         /* Create a new class coupling with a JavaScript constructor,
-         and add it to the global smalltalk object.*/
+         and add it to the system.*/
 
         this.addCoupledClass = function (className, superclass, pkgName, fn) {
             return rawAddClass(pkgName, className, superclass, null, fn);
@@ -469,7 +469,7 @@ define(['require', './brikz', './compatibility'], function (require, Brikz) {
         this.__init__.once = true;
 
         /* Smalltalk method object. To add a method to a class,
-         use smalltalk.addMethod() */
+         use api.addMethod() */
 
         st.method = function (spec) {
             var that = new SmalltalkMethod();
@@ -569,8 +569,6 @@ define(['require', './brikz', './compatibility'], function (require, Brikz) {
 
                 configureWithRuntime(brikz);
 
-                /* Alias definitions */
-
                 st.alias(globals.Array, "OrderedCollection");
                 st.alias(globals.Date, "Time");
 
@@ -642,7 +640,7 @@ define(['require', './brikz', './compatibility'], function (require, Brikz) {
         };
     }
 
-    /* Adds AMD and requirejs related methods to the smalltalk object */
+    /* Adds AMD and requirejs related methods to the api */
     function AMDBrik(brikz, st) {
         st.amdRequire = require;
         st.defaultTransportType = st.defaultTransportType || "amd";
@@ -661,9 +659,9 @@ define(['require', './brikz', './compatibility'], function (require, Brikz) {
          * It takes any value (JavaScript or Smalltalk)
          * and returns a proper Amber Smalltalk receiver.
          *
-         * null or undefined -> nil,
-         * plain JS object -> wrapped JS object,
-         * otherwise unchanged
+         * null or undefined -> nilAsReceiver,
+         * object having Smalltalk signature -> unchanged,
+         * otherwise wrapped foreign (JS) object
          */
         this.asReceiver = function (o) {
             if (o == null) return nilAsReceiver;

support/kernel-runtime.js

@@ -60,9 +60,6 @@ define(function () {
         var installMethod = brikz.manipulation.installMethod;
         var installJSMethod = brikz.manipulation.installJSMethod;
 
-        /* Initialize a class in its class hierarchy. Handle both classes and
-         metaclasses. */
-
         var detachedRootClasses = [];
 
         function markClassDetachedRoot(klass) {
@@ -74,6 +71,9 @@ define(function () {
             return detachedRootClasses;
         };
 
+        /* Initialize a class in its class hierarchy. Handle both classes and
+         metaclasses. */
+
         function initClassAndMetaclass(klass) {
             initClass(klass);
             if (klass.klass && !klass.meta) {
@@ -295,9 +295,10 @@ define(function () {
 
         setClassConstructor(globals.MethodContext, SmalltalkMethodContext);
 
-        /* This is the current call context object. While it is publicly available,
-         Use smalltalk.getThisContext() instead which will answer a safe copy of
-         the current context */
+        /* This is the current call context object.
+         In Smalltalk code, it is accessible just by using 'thisContext' variable.
+         In JS code, use api.getThisContext() (see below).
+         */
 
         var thisContext = null;
 
@@ -409,8 +410,7 @@ define(function () {
         var globals = brikz.smalltalkGlobals.globals;
         var nilAsReceiver = brikz.root.nilAsReceiver;
 
-        /* Handles unhandled errors during message sends */
-        // simply send the message and handle #dnu:
+        /* Send message programmatically. Used to implement #perform: & Co. */
 
         st.send2 = function (receiver, selector, args, klass) {
             var method, jsSelector = st.st2js(selector);
@@ -441,6 +441,13 @@ define(function () {
                 return invokeDnuMethod(receiver, stSelector, args);
             }
             /* Call a method of a JS object, or answer a property if it exists.
+
+             Converts keyword-based selectors by using the first
+             keyword only, but keeping all message arguments.
+
+             Example:
+             "self do: aBlock with: anObject" -> "self.do(aBlock, anObject)"
+
              Else try wrapping a JSObjectProxy around the receiver. */
             var propertyName = st.st2prop(stSelector);
             if (!(propertyName in receiver)) {
@@ -452,12 +459,7 @@ define(function () {
         /* If the object property is a function, then call it, except if it starts with
          an uppercase character (we probably want to answer the function itself in this
          case and send it #new from Amber).
-
-         Converts keyword-based selectors by using the first
-         keyword only, but keeping all message arguments.
-
-         Example:
-         "self do: aBlock with: anObject" -> "self.do(aBlock, anObject)" */
+         */
         function accessJavaScript(receiver, propertyName, args) {
             var propertyValue = receiver[propertyName];
             if (typeof propertyValue === "function" && !/^[A-Z]/.test(propertyName)) {