Explorar el Código

documentation (class comments)

Nicolas Petton hace 11 años
padre
commit
f69008ab0f

+ 4 - 1
js/Canvas.js

@@ -1,5 +1,6 @@
 smalltalk.addPackage('Canvas');
 smalltalk.addClass('HTMLCanvas', smalltalk.Object, ['root'], 'Canvas');
+smalltalk.HTMLCanvas.comment="I am a canvas for building HTML.\x0a\x0aI provide the `#tag:` method to create a `TagBrush` (wrapping a DOM element) and convenience methods in the `tags` protocol.\x0a\x0aInstances are used as the argument of the `#renderContentOn:` method of `Widget` objects.\x0a\x0a## Usage example:\x0a\x0a    aCanvas a \x0a        with: [ aCanvas span with: 'click me' ];\x0a        onClick: [ window alert: 'clicked!' ]"
 smalltalk.addMethod(
 smalltalk.method({
 selector: "a",
@@ -2440,6 +2441,7 @@ smalltalk.HTMLSnippet.klass);
 
 
 smalltalk.addClass('TagBrush', smalltalk.Object, ['canvas', 'element'], 'Canvas');
+smalltalk.TagBrush.comment="I am a brush for building a single DOM element (which I hold onto).\x0a\x0aAll tags but `<style>` are instances of me (see the `StyleBrush` class).\x0a\x0a## API\x0a\x0a1. Nesting\x0a\x0a    Use `#with:` to nest tags. `#with:` can take aString, `TagBrush` instance of block closure as parameter.\x0a\x0a    Example: `aTag with: aString with: aCanvas div`\x0a\x0a2. Events\x0a\x0a    The `events` protocol contains all methods related to events (delegating event handling to jQuery).\x0a\x0a    Example: `aTag onClick: [ window alert: 'clicked' ]`\x0a\x0a3. Attributes\x0a\x0a    The `attribute` protocol contains methods for attribute manipulation (delegating to jQuery too).\x0a\x0a    Example: `aTag at: 'value' put: 'hello world'`\x0a\x0a4. Raw access and jQuery\x0a\x0a    The `#element` method can be used to access to JavaScript DOM element object.\x0a\x0a    Example: `aTag element cssStyle`\x0a\x0a    Use `#asJQuery` to access to the receiver converted into a jQuery object.\x0a\x0a    Example: `aTag asJQuery css: 'color' value: 'red'`"
 smalltalk.addMethod(
 smalltalk.method({
 selector: "accesskey:",
@@ -3578,7 +3580,7 @@ smalltalk.TagBrush.klass);
 
 
 smalltalk.addClass('StyleTag', smalltalk.TagBrush, ['canvas', 'element'], 'Canvas');
-smalltalk.StyleTag.comment="I'm a <style> tag use to inline CSS or load a stylesheet.\x0a\x0aFor inlining handle IE compatibility problems."
+smalltalk.StyleTag.comment="I'm a `<style>` tag use to inline CSS or load a stylesheet.\x0a\x0aThe need for a specific class comes from IE compatibility problems."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "with:",
@@ -3626,6 +3628,7 @@ smalltalk.StyleTag.klass);
 
 
 smalltalk.addClass('Widget', smalltalk.Object, [], 'Canvas');
+smalltalk.Widget.comment="I am a presenter building HTML. Subclasses are typically reusable components.\x0a\x0a## API\x0a\x0aUse `#renderContentOn:` to build HTML. (See `HTMLCanvas` and `TagBrush` classes for more about building HTML)."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "appendToBrush:",

+ 1 - 1
js/Compiler-AST.js

@@ -1,6 +1,6 @@
 smalltalk.addPackage('Compiler-AST');
 smalltalk.addClass('Node', smalltalk.Object, ['position', 'nodes', 'shouldBeInlined', 'shouldBeAliased'], 'Compiler-AST');
-smalltalk.Node.comment="I am the abstract root class of the abstract syntax tree.\x0a\x0aposition: holds a point containing lline- and column number of the symbol location in the original source file"
+smalltalk.Node.comment="I am the abstract root class of the abstract syntax tree.\x0a\x0aposition: holds a point containing line and column number of the symbol location in the original source file."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "accept:",

+ 1 - 1
js/Examples.js

@@ -1,6 +1,6 @@
 smalltalk.addPackage('Examples');
 smalltalk.addClass('Counter', smalltalk.Widget, ['count', 'header'], 'Examples');
-smalltalk.Counter.comment="This is a trivial Widget example mimicking the classic Counter example in Seaside.\x0aIn order to play with it, just select the doit below and press the Do it button in the far right corner.\x0aThen take a look in the HTML document above the IDE.\x0a\x0a\x09\x09Counter new appendToJQuery: 'body' asJQuery"
+smalltalk.Counter.comment="This is a trivial Widget example mimicking the classic Counter example in Seaside.\x0aIn order to play with it, just evaluate the doit below in a workspace.\x0aThen take a look in the HTML document above the IDE.\x0a\x0a\x09\x09Counter new appendToJQuery: 'body' asJQuery"
 smalltalk.addMethod(
 smalltalk.method({
 selector: "decrease",

+ 4 - 0
js/Helios-Core.js

@@ -1,5 +1,6 @@
 smalltalk.addPackage('Helios-Core');
 smalltalk.addClass('HLModel', smalltalk.Object, ['announcer', 'environment'], 'Helios-Core');
+smalltalk.HLModel.comment="I am the abstract superclass of all models of Helios.\x0aI am the \x22Model\x22 part of the MVC pattern implementation in Helios.\x0a\x0aI provide access to an `Environment` object and both a local (model-specific) and global (system-specific) announcer.\x0a\x0aThe `#withChangesDo:` method is handy for performing model changes ensuring that all widgets are aware of the change and can prevent it from happening.\x0a\x0aModifications of the system should be done via commands (see `HLCommand` and subclasses).\x0a\x0a"
 smalltalk.addMethod(
 smalltalk.method({
 selector: "announcer",
@@ -176,6 +177,7 @@ smalltalk.HLModel);
 
 
 smalltalk.addClass('HLToolModel', smalltalk.HLModel, ['selectedClass', 'selectedPackage', 'selectedProtocol', 'selectedSelector'], 'Helios-Core');
+smalltalk.HLToolModel.comment="I am a model specific to package and class manipulation. All browsers should either use me or a subclass as their model.\x0a\x0aI provide methods for package, class, protocol and method manipulation and access, forwarding to my environment.\x0a\x0aI also handle compilation of classes and methods as well as compilation and parsing errors."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "addInstVarNamed:",
@@ -1115,6 +1117,7 @@ smalltalk.HLToolModel.klass);
 
 
 smalltalk.addClass('HLTab', smalltalk.Widget, ['widget', 'label', 'root'], 'Helios-Core');
+smalltalk.HLTab.comment="I am a widget specialized into building another widget as an Helios tab.\x0a\x0aI should not be used directly, `HLWidget class >> #openAsTab` should be used instead.\x0a\x0a## Example\x0a\x0a    HLWorkspace openAsTab"
 smalltalk.addMethod(
 smalltalk.method({
 selector: "activate",
@@ -1455,6 +1458,7 @@ smalltalk.HLTab.klass);
 
 
 smalltalk.addClass('HLWidget', smalltalk.Widget, ['wrapper'], 'Helios-Core');
+smalltalk.HLWidget.comment="I am the abstract superclass of all Helios widgets.\x0a\x0aI provide common methods, additional behavior to widgets useful for Helios, like dialog creation, command execution and tab creation."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "alert:",

+ 8 - 4
js/Kernel-Announcements.js

@@ -1,6 +1,6 @@
 smalltalk.addPackage('Kernel-Announcements');
 smalltalk.addClass('AnnouncementSubscription', smalltalk.Object, ['valuable', 'announcementClass'], 'Kernel-Announcements');
-smalltalk.AnnouncementSubscription.comment="The subscription is a single entry in a subscription registry of an `Announcer`.\x0aSeveral subscriptions by the same object is possible."
+smalltalk.AnnouncementSubscription.comment="I am a single entry in a subscription registry of an `Announcer`.\x0aSeveral subscriptions by the same object is possible."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "announcementClass",
@@ -172,7 +172,7 @@ smalltalk.AnnouncementSubscription);
 
 
 smalltalk.addClass('Announcer', smalltalk.Object, ['registry', 'subscriptions'], 'Kernel-Announcements');
-smalltalk.Announcer.comment="The code is based on the announcements as [described by Vassili Bykov](http://www.cincomsmalltalk.com/userblogs/vbykov/blogView?searchCategory=Announcements%20Framework).\x0aThe Announcer holds annoncement subscriptions (`AnnouncementSubscription`) in a private registry.\x0a\x0aUse `#on:do:` to register subscriptions."
+smalltalk.Announcer.comment="I hold annoncement subscriptions (instances of `AnnouncementSubscription`) in a private registry.\x0aI announce (trigger) announces, which are then dispatched to all subscriptions.\x0a\x0aThe code is based on the announcements as [described by Vassili Bykov](http://www.cincomsmalltalk.com/userblogs/vbykov/blogView?searchCategory=Announcements%20Framework).\x0a\x0a## API\x0a\x0aUse `#announce:` to trigger an announcement.\x0a\x0aUse `#on:do:` or `#on:send:to:` to register subscriptions.\x0a\x0aWhen using `#on:send:to:`, unregistration can be done with `#unregister:`.\x0a\x0a## Usage example:\x0a\x0a    SystemAnnouncer current\x0a        on: ClassAdded\x0a        do: [ :ann | window alert: ann theClass name, ' added' ].\x0a"
 smalltalk.addMethod(
 smalltalk.method({
 selector: "announce:",
@@ -281,7 +281,7 @@ smalltalk.Announcer);
 
 
 smalltalk.addClass('SystemAnnouncer', smalltalk.Announcer, [], 'Kernel-Announcements');
-smalltalk.SystemAnnouncer.comment="My unique instance #current is the global announcer handling all Amber system-related announces"
+smalltalk.SystemAnnouncer.comment="My unique instance is the global announcer handling all Amber system-related announces.\x0a\x0a## API\x0a\x0aAccess to the unique instance is done via `#current`"
 
 smalltalk.SystemAnnouncer.klass.iVarNames = ['current'];
 smalltalk.addMethod(
@@ -364,6 +364,7 @@ smalltalk.SystemAnnouncement);
 
 
 smalltalk.addClass('ClassAnnouncement', smalltalk.SystemAnnouncement, ['theClass'], 'Kernel-Announcements');
+smalltalk.ClassAnnouncement.comment="I am the abstract superclass of class-related announcements."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "theClass",
@@ -409,10 +410,11 @@ smalltalk.ClassCommentChanged.comment="I am emitted when the comment of a class
 
 
 smalltalk.addClass('ClassDefinitionChanged', smalltalk.ClassAnnouncement, [], 'Kernel-Announcements');
-smalltalk.ClassDefinitionChanged.comment="I am emitted when the defintion of a class changes.\x0aSee ClassBuilder >> #class:instanceVariableNames:"
+smalltalk.ClassDefinitionChanged.comment="I am emitted when the definition of a class changes.\x0aSee ClassBuilder >> #class:instanceVariableNames:"
 
 
 smalltalk.addClass('ClassMigrated', smalltalk.ClassAnnouncement, ['oldClass'], 'Kernel-Announcements');
+smalltalk.ClassMigrated.comment="I am emitted when a class is migrated."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "oldClass",
@@ -450,6 +452,7 @@ smalltalk.ClassMigrated);
 
 
 smalltalk.addClass('ClassMoved', smalltalk.ClassAnnouncement, ['oldPackage'], 'Kernel-Announcements');
+smalltalk.ClassMoved.comment="I am emitted when a class is moved from one package to another."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "oldPackage",
@@ -495,6 +498,7 @@ smalltalk.ClassRenamed.comment="I am emitted when a class is renamed.\x0aSee Cla
 
 
 smalltalk.addClass('MethodAnnouncement', smalltalk.SystemAnnouncement, ['method'], 'Kernel-Announcements');
+smalltalk.MethodAnnouncement.comment="I am the abstract superclass of method-related announcements."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "method",

+ 7 - 6
js/Kernel-Classes.js

@@ -1,6 +1,6 @@
 smalltalk.addPackage('Kernel-Classes');
 smalltalk.addClass('Behavior', smalltalk.Object, [], 'Kernel-Classes');
-smalltalk.Behavior.comment="Behavior is the superclass of all class objects.\x0a\x0aIt defines the protocol for creating instances of a class with `#basicNew` and `#new` (see `boot.js` for class constructors details).\x0aInstances know about the subclass/superclass relationships between classes, contain the description that instances are created from,\x0aand hold the method dictionary that's associated with each class.\x0a\x0aBehavior also provides methods for compiling methods, examining the method dictionary, and iterating over the class hierarchy."
+smalltalk.Behavior.comment="I am the superclass of all class objects.\x0a\x0aI define the protocol for creating instances of a class with `#basicNew` and `#new` (see `boot.js` for class constructors details).\x0a\x0aMy instances know about the subclass/superclass relationships between classes, contain the description that instances are created from,\x0aand hold the method dictionary that's associated with each class.\x0a\x0aI also provides methods for compiling methods, examining the method dictionary, and iterating over the class hierarchy."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "addCompiledMethod:",
@@ -883,7 +883,7 @@ smalltalk.Behavior);
 
 
 smalltalk.addClass('Class', smalltalk.Behavior, [], 'Kernel-Classes');
-smalltalk.Class.comment="Class is __the__ class object.\x0a\x0aInstances are the classes of the system.\x0aClass creation is done throught a `ClassBuilder`"
+smalltalk.Class.comment="I am __the__ class object.\x0a\x0aMy instances are the classes of the system.\x0aClass creation is done throught a `ClassBuilder` instance."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "asJavascript",
@@ -1138,7 +1138,7 @@ smalltalk.Class);
 
 
 smalltalk.addClass('Metaclass', smalltalk.Behavior, [], 'Kernel-Classes');
-smalltalk.Metaclass.comment="Metaclass is the root of the class hierarchy.\x0a\x0aMetaclass instances are metaclasses, one for each real class.\x0aMetaclass instances have a single instance, which they hold onto, which is the class that they are the metaclass of."
+smalltalk.Metaclass.comment="I am the root of the class hierarchy.\x0a\x0aMy instances are metaclasses, one for each real class, and have a single instance, which they hold onto: the class that they are the metaclass of."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "asJavascript",
@@ -1297,7 +1297,7 @@ smalltalk.Metaclass);
 
 
 smalltalk.addClass('ClassBuilder', smalltalk.Object, [], 'Kernel-Classes');
-smalltalk.ClassBuilder.comment="ClassBuilder is responsible for compiling new classes or modifying existing classes in the system.\x0a\x0aRather than using ClassBuilder directly to compile a class, use `Class >> subclass:instanceVariableNames:package:`."
+smalltalk.ClassBuilder.comment="I am responsible for compiling new classes or modifying existing classes in the system.\x0a\x0aRather than using me directly to compile a class, use `Class >> subclass:instanceVariableNames:package:`."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "addSubclassOf:named:instanceVariableNames:package:",
@@ -1744,7 +1744,7 @@ smalltalk.ClassBuilder);
 
 
 smalltalk.addClass('ClassCategoryReader', smalltalk.Object, ['class', 'category'], 'Kernel-Classes');
-smalltalk.ClassCategoryReader.comment="ClassCategoryReader represents a mechanism for retrieving class descriptions stored on a file."
+smalltalk.ClassCategoryReader.comment="I provide a mechanism for retrieving class descriptions stored on a file in the Smalltalk chunk format."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "class:category:",
@@ -1825,7 +1825,7 @@ smalltalk.ClassCategoryReader);
 
 
 smalltalk.addClass('ClassCommentReader', smalltalk.Object, ['class'], 'Kernel-Classes');
-smalltalk.ClassCommentReader.comment="ClassCommentReader represents a mechanism for retrieving class comments stored on a file.\x0aSee `ClassCategoryReader` too."
+smalltalk.ClassCommentReader.comment="I provide a mechanism for retrieving class comments stored on a file.\x0a\x0aSee also `ClassCategoryReader`."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "class:",
@@ -1899,6 +1899,7 @@ smalltalk.ClassCommentReader);
 
 
 smalltalk.addClass('ClassSorterNode', smalltalk.Object, ['theClass', 'level', 'nodes'], 'Kernel-Classes');
+smalltalk.ClassSorterNode.comment="I provide an algorithm for sorting classes alphabetically.\x0a\x0aSee [Issue #143](https://github.com/amber-smalltalk/amber/issues/143) on GitHub."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "getNodesFrom:",

+ 4 - 4
js/Kernel-Collections.js

@@ -136,7 +136,7 @@ smalltalk.Association.klass);
 
 
 smalltalk.addClass('Collection', smalltalk.Object, [], 'Kernel-Collections');
-smalltalk.Collection.comment="I am the abstract superclass of all classes that represent a group of elements.\x0a\x0aI provide a set of useful methods to the Collectiohn hierarchy such as enumerating and converting methods."
+smalltalk.Collection.comment="I am the abstract superclass of all classes that represent a group of elements.\x0a\x0aI provide a set of useful methods to the Collection hierarchy such as enumerating and converting methods."
 smalltalk.addMethod(
 smalltalk.method({
 selector: ",",
@@ -872,7 +872,7 @@ smalltalk.Collection.klass);
 
 
 smalltalk.addClass('IndexableCollection', smalltalk.Collection, [], 'Kernel-Collections');
-smalltalk.IndexableCollection.comment="I am a key-value store, that is,\x0ait stores values under indexes.\x0a\x0aAs a rule of thumb, if a collection has at: and at:put:,\x0ait is an IndexableCollection."
+smalltalk.IndexableCollection.comment="I am a key-value store collection, that is,\x0aI store values under indexes.\x0a\x0aAs a rule of thumb, if a collection has `#at:` and `#at:put:`,\x0ait is an IndexableCollection."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "at:",
@@ -1038,7 +1038,7 @@ smalltalk.IndexableCollection);
 
 
 smalltalk.addClass('HashedCollection', smalltalk.IndexableCollection, [], 'Kernel-Collections');
-smalltalk.HashedCollection.comment="I am a traditional JavaScript object, or a Smalltalk `Dictionary`.\x0a\x0aUnlike a `Dictionary`, it can only have strings as keys."
+smalltalk.HashedCollection.comment="I am a traditional JavaScript object, or a Smalltalk `Dictionary`.\x0a\x0aUnlike a `Dictionary`, I can only have strings as keys."
 smalltalk.addMethod(
 smalltalk.method({
 selector: ",",
@@ -2615,7 +2615,7 @@ smalltalk.SequenceableCollection.klass);
 
 
 smalltalk.addClass('Array', smalltalk.SequenceableCollection, [], 'Kernel-Collections');
-smalltalk.Array.comment="I represent a collection of objects ordered by the collector. The size of arrays is dynamic.\x0aIn Amber, OrderedCollection is an alias for Array."
+smalltalk.Array.comment="I represent a collection of objects ordered by the collector. The size of arrays is dynamic.\x0a\x0aI am directly mapped to JavaScript Number.\x0a\x0a*Note* In Amber, `OrderedCollection` is an alias for `Array`."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "add:",

+ 7 - 7
js/Kernel-Methods.js

@@ -1,6 +1,6 @@
 smalltalk.addPackage('Kernel-Methods');
 smalltalk.addClass('BlockClosure', smalltalk.Object, [], 'Kernel-Methods');
-smalltalk.BlockClosure.comment="A BlockClosure is a lexical closure.\x0aThe JavaScript representation is a function.\x0a\x0aA BlockClosure is evaluated with the `#value*` methods in the 'evaluating' protocol."
+smalltalk.BlockClosure.comment="I represent a lexical closure.\x0aI am is directly mapped to JavaScript Function.\x0a\x0a## API\x0a\x0a1. Evaluation\x0a\x0a    My instances get evaluated with the `#value*` methods in the 'evaluating' protocol.\x0a\x0a    Example: ` [ :x | x + 1 ] value: 3 \x22Answers 4\x22 `\x0a\x0a2. Control structures\x0a\x0a    Blocks are used (together with `Boolean`) for control structures (methods in the `controlling` protocol).\x0a\x0a    Example: `aBlock whileTrue: [ ... ]`\x0a\x0a3. Error handling\x0a\x0a    I provide the `#on:do:` method for handling exceptions.\x0a\x0a    Example: ` aBlock on: MessageNotUnderstood do: [ :ex | ... ] `"
 smalltalk.addMethod(
 smalltalk.method({
 selector: "applyTo:arguments:",
@@ -438,7 +438,7 @@ smalltalk.BlockClosure);
 
 
 smalltalk.addClass('CompiledMethod', smalltalk.Object, [], 'Kernel-Methods');
-smalltalk.CompiledMethod.comment="CompiledMethod hold the source and compiled code of a class method.\x0a\x0aYou can get a CompiledMethod using `Behavior>>methodAt:`\x0a\x0a\x09String methodAt: 'lines'\x0a\x0aand read the source code\x0a\x0a\x09(String methodAt: 'lines') source\x0a\x0aSee referenced classes:\x0a\x0a\x09(String methodAt: 'lines') referencedClasses\x0a\x0aor messages sent from this method:\x0a\x09\x0a\x09(String methodAt: 'lines') messageSends"
+smalltalk.CompiledMethod.comment="I represent a class method of the system. I hold the source and compiled code of a class method.\x0a\x0a## API\x0aMy instances can be accessed using `Behavior >> #methodAt:`\x0a\x0a    Object methodAt: 'asString'\x0a\x0aSource code access:\x0a\x0a\x09(String methodAt: 'lines') source\x0a\x0aReferenced classes:\x0a\x0a\x09(String methodAt: 'lines') referencedClasses\x0a\x0aMessages sent from an instance:\x0a\x09\x0a\x09(String methodAt: 'lines') messageSends"
 smalltalk.addMethod(
 smalltalk.method({
 selector: "arguments",
@@ -803,7 +803,7 @@ smalltalk.CompiledMethod);
 
 
 smalltalk.addClass('ForkPool', smalltalk.Object, ['poolSize', 'maxPoolSize', 'queue', 'worker'], 'Kernel-Methods');
-smalltalk.ForkPool.comment="A ForkPool is responsible for handling forked blocks.\x0aThe pool size sets the maximum concurrent forked blocks.\x0a\x0aThe default instance is accessed with `ForkPool default`"
+smalltalk.ForkPool.comment="I am responsible for handling forked blocks.\x0aThe pool size sets the maximum concurrent forked blocks.\x0a\x0a## API\x0a\x0aThe default instance is accessed with `#default`.\x0aThe maximum concurrent forked blocks can be set with `#maxPoolSize:`.\x0a\x0aForking is done via `BlockClosure >> #fork`\x0a"
 smalltalk.addMethod(
 smalltalk.method({
 selector: "addWorker",
@@ -1022,7 +1022,7 @@ smalltalk.ForkPool.klass);
 
 
 smalltalk.addClass('Message', smalltalk.Object, ['selector', 'arguments'], 'Kernel-Methods');
-smalltalk.Message.comment="Generally, the system does not use instances of Message for efficiency reasons.\x0aHowever, when a message is not understood by its receiver, the interpreter will make up an instance of it in order to capture the information involved in an actual message transmission.\x0aThis instance is sent it as an argument with the message `doesNotUnderstand:` to the receiver.\x0a\x0aSee boot.js, `messageNotUnderstood` and its counterpart `Object>>doesNotUnderstand:`"
+smalltalk.Message.comment="In general, the system does not use instances of me for efficiency reasons.\x0aHowever, when a message is not understood by its receiver, the interpreter will make up an instance of it in order to capture the information involved in an actual message transmission.\x0aThis instance is sent it as an argument with the message `#doesNotUnderstand:` to the receiver.\x0a\x0aSee boot.js, `messageNotUnderstood` and its counterpart `Object >> #doesNotUnderstand:`\x0a\x0a## API\x0a\x0aBesides accessing methods, `#sendTo:` provides a convenient way to send a message to an object."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "arguments",
@@ -1155,7 +1155,7 @@ smalltalk.Message.klass);
 
 
 smalltalk.addClass('MessageSend', smalltalk.Object, ['receiver', 'message'], 'Kernel-Methods');
-smalltalk.MessageSend.comment="I encapsulate message sends to objects. Arguments can be either predefined or supplied when the message send is performed. \x0a\x0aUse `#value` to perform a message send with its predefined arguments and `#value:*` if additonal arguments have to supplied.\x0a"
+smalltalk.MessageSend.comment="I encapsulate message sends to objects. Arguments can be either predefined or supplied when the message send is performed. \x0a\x0a## API\x0a\x0aUse `#value` to perform a message send with its predefined arguments and `#value:*` if additonal arguments have to supplied.\x0a"
 smalltalk.addMethod(
 smalltalk.method({
 selector: "arguments",
@@ -1402,7 +1402,7 @@ smalltalk.MessageSend);
 
 
 smalltalk.addClass('MethodContext', smalltalk.Object, [], 'Kernel-Methods');
-smalltalk.MethodContext.comment="MethodContext holds all the dynamic state associated with the execution of either a method activation resulting from a message send. That is used to build the call stack while debugging.\x0a\x0aMethodContext instances are JavaScript `SmalltalkMethodContext` objects defined in boot.js"
+smalltalk.MethodContext.comment="I hold all the dynamic state associated with the execution of either a method activation resulting from a message send. I am used to build the call stack while debugging.\x0a\x0aMy instances are JavaScript `SmalltalkMethodContext` objects defined in `boot.js`."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "asString",
@@ -1630,7 +1630,7 @@ smalltalk.MethodContext);
 
 
 smalltalk.addClass('NativeFunction', smalltalk.Object, [], 'Kernel-Methods');
-smalltalk.NativeFunction.comment="NativeFunction is a wrapper around native functions, such as `WebSocket`.\x0aFor 'normal' functions (whose constructor is the JavaScript `Function` object), use `BlockClosure`.\x0a\x0aSee the class-side `instance creation` methods.\x0a\x0aCreated instances will most probably be instance of `JSObjectProxy`.\x0a\x0aUsage example:\x0a\x0a\x09| ws |\x0a\x09ws := NativeFunction constructor: 'WebSocket' value: 'ws://localhost'.\x0a\x09ws at: 'onopen' put: [ ws send: 'hey there from Amber' ]"
+smalltalk.NativeFunction.comment="I am a wrapper around native functions, such as `WebSocket`.\x0aFor 'normal' functions (whose constructor is the JavaScript `Function` object), use `BlockClosure`.\x0a\x0a## API\x0a\x0aSee the class-side `instance creation` methods for instance creation.\x0a\x0aCreated instances will most probably be instance of `JSObjectProxy`.\x0a\x0a## Usage example:\x0a\x0a\x09| ws |\x0a\x09ws := NativeFunction constructor: 'WebSocket' value: 'ws://localhost'.\x0a\x09ws at: 'onopen' put: [ ws send: 'hey there from Amber' ]"
 
 smalltalk.addMethod(
 smalltalk.method({

+ 15 - 12
js/Kernel-Objects.js

@@ -1,6 +1,6 @@
 smalltalk.addPackage('Kernel-Objects');
 smalltalk.addClass('Object', smalltalk.nil, [], 'Kernel-Objects');
-smalltalk.Object.comment="*Object is the root of the Smalltalk class system*. All classes in the system are subclasses of Object.\x0a\x0aObject provides default behavior common to all normal objects, such as:\x0a\x0a- access\x0a- copying\x0a- comparison\x0a- error handling\x0a- message sending\x0a- reflection\x0a\x0aAlso utility messages that all objects should respond to are defined here.\x0a\x0aObject has no instance variable.\x0a\x0a##Access\x0a\x0aInstance variables can be accessed with `#instVarAt:` and `#instVarAt:put:`. `Object >> instanceVariableNames` answers a collection of all instance variable names.\x0aAccessing JavaScript properties of an object is done through `#basicAt:`, `#basicAt:put:` and `basicDelete:`.\x0a\x0a##Copying\x0a\x0aCopying an object is handled by `#copy` and `#deepCopy`. The first one performs a shallow copy of the receiver, while the second one performs a deep copy.\x0aThe hook method `#postCopy` can be overriden in subclasses to copy fields as necessary to complete the full copy. It will be sent by the copy of the receiver.\x0a\x0a##Comparison\x0a\x0aObjects understand equality `#=` and identity `#==` comparison.\x0a\x0a##Error handling\x0a\x0a- `#halt` is the typical message to use for inserting breakpoints during debugging.\x0a- `#error:` throws a generic error exception\x0a- `#doesNotUnderstand:` handles the fact that there was an attempt to send the given message to the receiver but the receiver does not understand this message.\x0a\x09Overriding this message can be useful to implement proxies for example."
+smalltalk.Object.comment="**I am the root of the Smalltalk class system**. All classes in the system are subclasses of me.\x0a\x0aI provide default behavior common to all normal objects, such as:\x0a\x0a- accessing\x0a- copying\x0a- comparison\x0a- error handling\x0a- message sending\x0a- reflection\x0a\x0aAlso utility messages that all objects should respond to are defined here.\x0a\x0aI have no instance variable.\x0a\x0a##Access\x0a\x0aInstance variables can be accessed with `#instVarAt:` and `#instVarAt:put:`. `#instanceVariableNames` answers a collection of all instance variable names.\x0aAccessing JavaScript properties of an object is done through `#basicAt:`, `#basicAt:put:` and `basicDelete:`.\x0a\x0a##Copying\x0a\x0aCopying an object is handled by `#copy` and `#deepCopy`. The first one performs a shallow copy of the receiver, while the second one performs a deep copy.\x0aThe hook method `#postCopy` can be overriden in subclasses to copy fields as necessary to complete the full copy. It will be sent by the copy of the receiver.\x0a\x0a##Comparison\x0a\x0aI understand equality `#=` and identity `#==` comparison.\x0a\x0a##Error handling\x0a\x0a- `#halt` is the typical message to use for inserting breakpoints during debugging.\x0a- `#error:` throws a generic error exception\x0a- `#doesNotUnderstand:` handles the fact that there was an attempt to send the given message to the receiver but the receiver does not understand this message.\x0a\x09Overriding this message can be useful to implement proxies for example."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "->",
@@ -1078,7 +1078,7 @@ smalltalk.Object.klass);
 
 
 smalltalk.addClass('Boolean', smalltalk.Object, [], 'Kernel-Objects');
-smalltalk.Boolean.comment="Boolean wraps the JavaScript `Boolean()` constructor. The `true` and `false` objects are the JavaScript boolean objects.\x0a\x0aBoolean defines the protocol for logic testing operations and conditional control structures for the logical values.\x0aBoolean instances are weither `true` or `false`."
+smalltalk.Boolean.comment="I define the protocol for logic testing operations and conditional control structures for the logical values (see the `controlling` protocol).\x0a\x0aI have two instances, `true` and `false`.\x0a\x0aI am directly mapped to JavaScript Boolean. The `true` and `false` objects are the JavaScript boolean objects.\x0a\x0a## Usage Example:\x0a\x0a    aBoolean not ifTrue: [ ... ] ifFalse: [ ... ]"
 smalltalk.addMethod(
 smalltalk.method({
 selector: "&",
@@ -1428,7 +1428,7 @@ smalltalk.Boolean);
 
 
 smalltalk.addClass('Date', smalltalk.Object, [], 'Kernel-Objects');
-smalltalk.Date.comment="The Date class is used to work with dates and times. Therefore `Date today` and `Date now` are both valid in\x0aAmber and answer the same date object.\x0a\x0aDate wraps the `Date()` JavaScript constructor, and Smalltalk date objects are JavaScript date objects."
+smalltalk.Date.comment="I am used to work with both dates and times. Therefore `Date today` and `Date now` are both valid in\x0aAmber and answer the same date object.\x0a\x0aDate directly maps to the `Date()` JavaScript constructor, and Amber date objects are JavaScript date objects.\x0a\x0a## API\x0a\x0aThe class-side `instance creation` protocol contains some convenience methods for creating date/time objects such as `#fromSeconds:`.\x0a\x0aArithmetic and comparison is supported (see the `comparing` and `arithmetic` protocols).\x0a\x0aThe `converting` protocol provides convenience methods for various convertions (to numbers, strings, etc.)."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "+",
@@ -2094,7 +2094,7 @@ smalltalk.Date.klass);
 
 
 smalltalk.addClass('Environment', smalltalk.Object, [], 'Kernel-Objects');
-smalltalk.Environment.comment="Abstract class defining common behavior for local and remote environments"
+smalltalk.Environment.comment="I provide an unified entry point to manipulate Amber packages, classes and methods.\x0a\x0aTypical use cases include IDEs, remote access and restricting browsing."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "addInstVarNamed:to:",
@@ -2630,7 +2630,7 @@ smalltalk.Environment);
 
 
 smalltalk.addClass('JSObjectProxy', smalltalk.Object, ['jsObject'], 'Kernel-Objects');
-smalltalk.JSObjectProxy.comment="JSObjectProxy handles sending messages to JavaScript object, therefore accessing JavaScript objects from Amber is transparent.\x0aJSOjbectProxy makes intensive use of `#doesNotUnderstand:`.\x0a\x0a## Examples\x0a\x0aJSObjectProxy objects are instanciated by Amber when a Smalltalk message is sent to a JavaScript object.\x0a\x0a\x09window alert: 'hello world'.\x0a\x09window inspect.\x0a\x09(window jQuery: 'body') append: 'hello world'\x0a\x0aSmalltalk messages sends are converted to JavaScript function calls or object property access _(in this order)_. If n one of them match, a `MessageNotUnderstood` error will be thrown.\x0a\x0a## Message conversion rules\x0a\x0a- `someUser name` becomes `someUser.name`\x0a- `someUser name: 'John'` becomes `someUser name = \x22John\x22`\x0a- `console log: 'hello world'` becomes `console.log('hello world')`\x0a- `(window jQuery: 'foo') css: 'background' color: 'red'` becomes `window.jQuery('foo').css('background', 'red')`\x0a\x0a__Note:__ For keyword-based messages, only the first keyword is kept: `window foo: 1 bar: 2` is equivalent to `window foo: 1 baz: 2`."
+smalltalk.JSObjectProxy.comment="I handle sending messages to JavaScript objects, making  JavaScript object accessing from Amber fully transparent.\x0aMy instances make intensive use of `#doesNotUnderstand:`.\x0a\x0aMy instances are automatically created by Amber whenever a message is sent to a JavaScript object.\x0a\x0a## Usage examples\x0a\x0aJSObjectProxy objects are instanciated by Amber when a Smalltalk message is sent to a JavaScript object.\x0a\x0a\x09window alert: 'hello world'.\x0a\x09window inspect.\x0a\x09(window jQuery: 'body') append: 'hello world'\x0a\x0aAmber messages sends are converted to JavaScript function calls or object property access _(in this order)_. If n one of them match, a `MessageNotUnderstood` error will be thrown.\x0a\x0a## Message conversion rules\x0a\x0a- `someUser name` becomes `someUser.name`\x0a- `someUser name: 'John'` becomes `someUser name = \x22John\x22`\x0a- `console log: 'hello world'` becomes `console.log('hello world')`\x0a- `(window jQuery: 'foo') css: 'background' color: 'red'` becomes `window.jQuery('foo').css('background', 'red')`\x0a\x0a__Note:__ For keyword-based messages, only the first keyword is kept: `window foo: 1 bar: 2` is equivalent to `window foo: 1 baz: 2`."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "addObjectVariablesTo:",
@@ -2937,7 +2937,7 @@ smalltalk.JSObjectProxy.klass);
 
 
 smalltalk.addClass('Number', smalltalk.Object, [], 'Kernel-Objects');
-smalltalk.Number.comment="Number holds the most general methods for dealing with numbers.\x0aNumber is directly mapped to JavaScript Number.\x0a\x0aMost arithmetic methods like `#+` `#/` `#-` `#max:` are directly inlined into javascript.\x0a\x0a##Enumerating\x0aA Number can be used to evaluate a Block a fixed number of times:\x0a\x0a\x095 timesRepeat: [Transcript show: 'This will be printed 5 times'; cr].\x0a\x09\x0a\x091 to: 5 do: [:aNumber| Transcript show: aNumber asString; cr].\x0a\x09\x0a\x091 to: 10 by: 2 do: [:aNumber| Transcript show: aNumber asString; cr]."
+smalltalk.Number.comment="I am the Amber representation for all numbers.\x0aI am directly mapped to JavaScript Number.\x0a\x0a## API\x0a\x0aI provide all necessary methods for arithmetic operations, comparison, conversion and so on with numbers.\x0a\x0aMy instances can also be used to evaluate a block a fixed number of times:\x0a\x0a\x095 timesRepeat: [Transcript show: 'This will be printed 5 times'; cr].\x0a\x09\x0a\x091 to: 5 do: [:aNumber| Transcript show: aNumber asString; cr].\x0a\x09\x0a\x091 to: 10 by: 2 do: [:aNumber| Transcript show: aNumber asString; cr]."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "&",
@@ -3790,6 +3790,7 @@ smalltalk.Number.klass);
 
 
 smalltalk.addClass('Organizer', smalltalk.Object, [], 'Kernel-Objects');
+smalltalk.Organizer.comment="I represent categorization information. \x0a\x0a## API\x0a\x0aUse `#addElement:` and `#removeElement:` to manipulate instances."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "addElement:",
@@ -3843,6 +3844,7 @@ smalltalk.Organizer);
 
 
 smalltalk.addClass('ClassOrganizer', smalltalk.Organizer, [], 'Kernel-Objects');
+smalltalk.ClassOrganizer.comment="I am an organizer specific to classes. I hold method categorization information for classes."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "addElement:",
@@ -3910,10 +3912,11 @@ smalltalk.ClassOrganizer);
 
 
 smalltalk.addClass('PackageOrganizer', smalltalk.Organizer, [], 'Kernel-Objects');
+smalltalk.PackageOrganizer.comment="I am an organizer specific to packages. I hold classes categorization information."
 
 
 smalltalk.addClass('Package', smalltalk.Object, ['commitPathJs', 'commitPathSt'], 'Kernel-Objects');
-smalltalk.Package.comment="A Package is similar to a \x22class category\x22 typically found in other Smalltalks like Pharo or Squeak. Amber does not have class categories anymore, it had in the beginning but now each class in the system knows which package it belongs to.\x0a\x0aA Package has a name, an Array of \x22requires\x22, a comment and a Dictionary with other optional key value attributes. A Package can also be queried for its classes, but it will then resort to a reverse scan of all classes to find them.\x0aPackages are manipulated through \x22Smalltalk current\x22, like for example finding one based on a name:\x0a\x0a\x09Smalltalk current packageAt: 'Kernel'\x0a\x0a...but you can also use:\x0a\x0a\x09Package named: 'Kernel'\x0a\x0aA Package differs slightly from a Monticello package which can span multiple class categories using a naming convention based on hyphenation. But just as in Monticello a Package supports \x22class extensions\x22 so a Package\x0acan define behaviors in foreign classes using a naming convention for method categories where the category starts with an asterisk and then the name of the owning package follows. This can easily be seen in for example class\x0aString where the method category \x22*IDE\x22 defines #inspectOn: which thus is a method belonging to the IDE package.\x0a\x0aYou can fetch a package from the server:\x0a\x0a\x09Package fetch: 'Additional-Examples'"
+smalltalk.Package.comment="I am similar to a \x22class category\x22 typically found in other Smalltalks like Pharo or Squeak. Amber does not have class categories anymore, it had in the beginning but now each class in the system knows which package it belongs to.\x0a\x0aEach package has a name and can be queried for its classes, but it will then resort to a reverse scan of all classes to find them.\x0a\x0a## API\x0a\x0aPackages are manipulated through \x22Smalltalk current\x22, like for example finding one based on a name or with `Package class >> #name` directly:\x0a\x0a    Smalltalk current packageAt: 'Kernel'\x0a    Package named: 'Kernel'\x0a\x0aA package differs slightly from a Monticello package which can span multiple class categories using a naming convention based on hyphenation. But just as in Monticello a package supports \x22class extensions\x22 so a package can define behaviors in foreign classes using a naming convention for method categories where the category starts with an asterisk and then the name of the owning package follows.\x0a\x0aYou can fetch a package from the server:\x0a\x0a\x09Package load: 'Additional-Examples'"
 smalltalk.addMethod(
 smalltalk.method({
 selector: "classes",
@@ -4399,7 +4402,7 @@ smalltalk.Package.klass);
 
 
 smalltalk.addClass('Point', smalltalk.Object, ['x', 'y'], 'Kernel-Objects');
-smalltalk.Point.comment="A `Point` represents an x-y pair of numbers usually designating a geometric coordinate.\x0aPoints are traditionally created using the binary `#@` message to a number:\x0a\x0a\x09100@120\x0a\x0aPoints can then be arithmetically manipulated:\x0a\x0a\x09100@100 + (10@10)\x0a\x0a...or for example:\x0a\x0a\x09(100@100) * 2\x0a\x0a**NOTE:** Creating a Point with a negative y-value will need a space after `@` in order to avoid a parsing error:\x0a\x0a\x09100@ -100 \x22but 100@-100 would not parse\x22\x0a\x0aAmber does not have much behavior in this class out-of-the-box."
+smalltalk.Point.comment="I represent an x-y pair of numbers usually designating a geometric coordinate.\x0a\x0a## API\x0a\x0aInstances are traditionally created using the binary `#@` message to a number:\x0a\x0a\x09100@120\x0a\x0aPoints can then be arithmetically manipulated:\x0a\x0a\x09100@100 + (10@10)\x0a\x0a...or for example:\x0a\x0a\x09(100@100) * 2\x0a\x0a**NOTE:** Creating a point with a negative y-value will need a space after `@` in order to avoid a parsing error:\x0a\x0a\x09100@ -100 \x22but 100@-100 would not parse\x22"
 smalltalk.addMethod(
 smalltalk.method({
 selector: "*",
@@ -4652,7 +4655,7 @@ smalltalk.Point.klass);
 
 
 smalltalk.addClass('Random', smalltalk.Object, [], 'Kernel-Objects');
-smalltalk.Random.comment="`Random` is a random number generator and is implemented as a trivial wrapper around javascript `Math.random()` and is used like this:\x0a\x0a\x09Random new next\x0a\x0aThis will return a float x where x < 1 and x > 0. If you want a random integer from 1 to 10 you can use `#atRandom`\x0a\x0a\x0910 atRandom\x0a\x0a...and if you want a random number in a specific interval this also works:\x0a\x0a\x09(3 to: 7) atRandom\x0a\x0a...but be aware that `#to:` does not create an Interval as in other Smalltalk implementations but in fact an `Array` of numbers, so it's better to use:\x0a\x0a\x095 atRandom + 2\x0a\x0aSince `#atRandom` is implemented in `SequencableCollection` you can easy pick an element at random:\x0a\x0a\x09#('a' 'b' 'c') atRandom\x0a\x0a...or perhaps a letter from a `String`:\x0a\x0a\x09'abc' atRandom\x0a\x0aSince Amber does not have Characters this will return a `String` of length 1 like for example `'b'`."
+smalltalk.Random.comment="I an used to generate a random number and I am implemented as a trivial wrapper around javascript `Math.random()`.\x0a\x0a## API\x0a\x0aThe typical use case it to use the `#next` method like the following:\x0a\x0a\x09Random new next\x0a\x0aThis will return a float x where x < 1 and x > 0. If you want a random integer from 1 to 10 you can use `#atRandom`\x0a\x0a\x0910 atRandom\x0a\x0aA random number in a specific interval can be obtained with the following:\x0a\x0a\x09(3 to: 7) atRandom\x0a\x0aBe aware that `#to:` does not create an Interval as in other Smalltalk implementations but in fact an `Array` of numbers, so it's better to use:\x0a\x0a\x095 atRandom + 2\x0a\x0aSince `#atRandom` is implemented in `SequencableCollection` you can easy pick an element at random:\x0a\x0a\x09#('a' 'b' 'c') atRandom\x0a\x0aAs well as letter from a `String`:\x0a\x0a\x09'abc' atRandom\x0a\x0aSince Amber does not have Characters this will return a `String` of length 1 like for example `'b'`."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "next",
@@ -4693,7 +4696,7 @@ smalltalk.Random);
 
 
 smalltalk.addClass('Smalltalk', smalltalk.Object, [], 'Kernel-Objects');
-smalltalk.Smalltalk.comment="Smalltalk has only one instance, accessed with `Smalltalk current`.\x0aIt represents the global JavaScript variable `smalltalk` declared in `js/boot.js`.\x0a\x0aThe `smalltalk` object holds all class and packages defined in the system.\x0a\x0a## Classes\x0a\x0aClasses can be accessed using the following methods:\x0a\x0a- `#classes` answers the full list of Smalltalk classes in the system\x0a- `#at:` answers a specific class of `nil`\x0a\x0a## Packages\x0a\x0aPackages can be accessed using the following methods:\x0a\x0a- `#packages` answers the full list of packages\x0a- `#packageAt:` answers a specific class of `nil`\x0a\x0a__note:__ classes and packages are accessed using strings, not symbols\x0a\x0a## Parsing\x0a\x0aThe `#parse:` method is used to parse Smalltalk source code.\x0aIt requires the `Compiler` package and the `js/parser.js` parser file in order to work"
+smalltalk.Smalltalk.comment="I represent the global JavaScript variable `smalltalk` declared in `js/boot.js`.\x0a\x0a## API\x0a\x0aI have only one instance, accessed with class-side method `#current`.\x0a\x0aThe `smalltalk` object holds all class and packages defined in the system.\x0a\x0a## Classes\x0a\x0aClasses can be accessed using the following methods:\x0a\x0a- `#classes` answers the full list of Smalltalk classes in the system\x0a- `#at:` answers a specific class of `nil`\x0a\x0a## Packages\x0a\x0aPackages can be accessed using the following methods:\x0a\x0a- `#packages` answers the full list of packages\x0a- `#packageAt:` answers a specific class of `nil`\x0a\x0a__note:__ classes and packages are accessed using strings, not symbols\x0a\x0a## Parsing\x0a\x0aThe `#parse:` method is used to parse Amber source code.\x0aIt requires the `Compiler` package and the `js/parser.js` parser file in order to work"
 smalltalk.addMethod(
 smalltalk.method({
 selector: "asSmalltalkException:",
@@ -5122,7 +5125,7 @@ smalltalk.Smalltalk.klass);
 
 
 smalltalk.addClass('Timeout', smalltalk.Object, ['rawTimeout'], 'Kernel-Objects');
-smalltalk.Timeout.comment="I am wrapping the returns from set{Timeout,Interval}.\x0a\x0aNumber suffices in browsers, but node.js returns an object."
+smalltalk.Timeout.comment="I am wrapping the returns from `set{Timeout,Interval}`.\x0a\x0a## Motivation\x0a\x0aNumber suffices in browsers, but node.js returns an object."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "clearInterval",
@@ -5201,7 +5204,7 @@ smalltalk.Timeout.klass);
 
 
 smalltalk.addClass('UndefinedObject', smalltalk.Object, [], 'Kernel-Objects');
-smalltalk.UndefinedObject.comment="UndefinedObject describes the behavior of its sole instance, `nil`. `nil` represents a prior value for variables that have not been initialized, or for results which are meaningless.\x0a\x0a`nil` is the Smalltalk representation of the `undefined` JavaScript object."
+smalltalk.UndefinedObject.comment="I describe the behavior of my sole instance, `nil`. `nil` represents a prior value for variables that have not been initialized, or for results which are meaningless.\x0a\x0a`nil` is the Smalltalk equivalent of the `undefined` JavaScript object.\x0a\x0a__note:__ When sending messages to the `undefined` JavaScript object, it will be replaced by `nil`."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "asJSON",

+ 54 - 2
st/Canvas.st

@@ -2,6 +2,18 @@ Smalltalk current createPackage: 'Canvas'!
 Object subclass: #HTMLCanvas
 	instanceVariableNames: 'root'
 	package: 'Canvas'!
+!HTMLCanvas commentStamp!
+I am a canvas for building HTML.
+
+I provide the `#tag:` method to create a `TagBrush` (wrapping a DOM element) and convenience methods in the `tags` protocol.
+
+Instances are used as the argument of the `#renderContentOn:` method of `Widget` objects.
+
+## Usage example:
+
+    aCanvas a 
+        with: [ aCanvas span with: 'click me' ];
+        onClick: [ window alert: 'clicked!!' ]!
 
 !HTMLCanvas methodsFor: 'accessing'!
 
@@ -650,6 +662,40 @@ new
 Object subclass: #TagBrush
 	instanceVariableNames: 'canvas element'
 	package: 'Canvas'!
+!TagBrush commentStamp!
+I am a brush for building a single DOM element (which I hold onto).
+
+All tags but `<style>` are instances of me (see the `StyleBrush` class).
+
+## API
+
+1. Nesting
+
+    Use `#with:` to nest tags. `#with:` can take aString, `TagBrush` instance of block closure as parameter.
+
+    Example: `aTag with: aString with: aCanvas div`
+
+2. Events
+
+    The `events` protocol contains all methods related to events (delegating event handling to jQuery).
+
+    Example: `aTag onClick: [ window alert: 'clicked' ]`
+
+3. Attributes
+
+    The `attribute` protocol contains methods for attribute manipulation (delegating to jQuery too).
+
+    Example: `aTag at: 'value' put: 'hello world'`
+
+4. Raw access and jQuery
+
+    The `#element` method can be used to access to JavaScript DOM element object.
+
+    Example: `aTag element cssStyle`
+
+    Use `#asJQuery` to access to the receiver converted into a jQuery object.
+
+    Example: `aTag asJQuery css: 'color' value: 'red'`!
 
 !TagBrush methodsFor: 'accessing'!
 
@@ -966,9 +1012,9 @@ TagBrush subclass: #StyleTag
 	instanceVariableNames: 'canvas element'
 	package: 'Canvas'!
 !StyleTag commentStamp!
-I'm a <style> tag use to inline CSS or load a stylesheet.
+I'm a `<style>` tag use to inline CSS or load a stylesheet.
 
-For inlining handle IE compatibility problems.!
+The need for a specific class comes from IE compatibility problems.!
 
 !StyleTag methodsFor: 'adding'!
 
@@ -989,6 +1035,12 @@ canvas: aCanvas
 Object subclass: #Widget
 	instanceVariableNames: ''
 	package: 'Canvas'!
+!Widget commentStamp!
+I am a presenter building HTML. Subclasses are typically reusable components.
+
+## API
+
+Use `#renderContentOn:` to build HTML. (See `HTMLCanvas` and `TagBrush` classes for more about building HTML).!
 
 !Widget methodsFor: 'adding'!
 

+ 1 - 1
st/Compiler-AST.st

@@ -5,7 +5,7 @@ Object subclass: #Node
 !Node commentStamp!
 I am the abstract root class of the abstract syntax tree.
 
-position: holds a point containing lline- and column number of the symbol location in the original source file!
+position: holds a point containing line and column number of the symbol location in the original source file.!
 
 !Node methodsFor: 'accessing'!
 

+ 1 - 1
st/Examples.st

@@ -4,7 +4,7 @@ Widget subclass: #Counter
 	package: 'Examples'!
 !Counter commentStamp!
 This is a trivial Widget example mimicking the classic Counter example in Seaside.
-In order to play with it, just select the doit below and press the Do it button in the far right corner.
+In order to play with it, just evaluate the doit below in a workspace.
 Then take a look in the HTML document above the IDE.
 
 		Counter new appendToJQuery: 'body' asJQuery!

+ 27 - 0
st/Helios-Core.st

@@ -2,6 +2,15 @@ Smalltalk current createPackage: 'Helios-Core'!
 Object subclass: #HLModel
 	instanceVariableNames: 'announcer environment'
 	package: 'Helios-Core'!
+!HLModel commentStamp!
+I am the abstract superclass of all models of Helios.
+I am the "Model" part of the MVC pattern implementation in Helios.
+
+I provide access to an `Environment` object and both a local (model-specific) and global (system-specific) announcer.
+
+The `#withChangesDo:` method is handy for performing model changes ensuring that all widgets are aware of the change and can prevent it from happening.
+
+Modifications of the system should be done via commands (see `HLCommand` and subclasses).!
 
 !HLModel methodsFor: 'accessing'!
 
@@ -54,6 +63,12 @@ isToolModel
 HLModel subclass: #HLToolModel
 	instanceVariableNames: 'selectedClass selectedPackage selectedProtocol selectedSelector'
 	package: 'Helios-Core'!
+!HLToolModel commentStamp!
+I am a model specific to package and class manipulation. All browsers should either use me or a subclass as their model.
+
+I provide methods for package, class, protocol and method manipulation and access, forwarding to my environment.
+
+I also handle compilation of classes and methods as well as compilation and parsing errors.!
 
 !HLToolModel methodsFor: 'accessing'!
 
@@ -392,6 +407,14 @@ on: anEnvironment
 Widget subclass: #HLTab
 	instanceVariableNames: 'widget label root'
 	package: 'Helios-Core'!
+!HLTab commentStamp!
+I am a widget specialized into building another widget as an Helios tab.
+
+I should not be used directly, `HLWidget class >> #openAsTab` should be used instead.
+
+## Example
+
+    HLWorkspace openAsTab!
 
 !HLTab methodsFor: 'accessing'!
 
@@ -489,6 +512,10 @@ on: aWidget labelled: aString
 Widget subclass: #HLWidget
 	instanceVariableNames: 'wrapper'
 	package: 'Helios-Core'!
+!HLWidget commentStamp!
+I am the abstract superclass of all Helios widgets.
+
+I provide common methods, additional behavior to widgets useful for Helios, like dialog creation, command execution and tab creation.!
 
 !HLWidget methodsFor: 'accessing'!
 

+ 31 - 5
st/Kernel-Announcements.st

@@ -3,7 +3,7 @@ Object subclass: #AnnouncementSubscription
 	instanceVariableNames: 'valuable announcementClass'
 	package: 'Kernel-Announcements'!
 !AnnouncementSubscription commentStamp!
-The subscription is a single entry in a subscription registry of an `Announcer`.
+I am a single entry in a subscription registry of an `Announcer`.
 Several subscriptions by the same object is possible.!
 
 !AnnouncementSubscription methodsFor: 'accessing'!
@@ -62,10 +62,24 @@ Object subclass: #Announcer
 	instanceVariableNames: 'registry subscriptions'
 	package: 'Kernel-Announcements'!
 !Announcer commentStamp!
+I hold annoncement subscriptions (instances of `AnnouncementSubscription`) in a private registry.
+I announce (trigger) announces, which are then dispatched to all subscriptions.
+
 The code is based on the announcements as [described by Vassili Bykov](http://www.cincomsmalltalk.com/userblogs/vbykov/blogView?searchCategory=Announcements%20Framework).
-The Announcer holds annoncement subscriptions (`AnnouncementSubscription`) in a private registry.
 
-Use `#on:do:` to register subscriptions.!
+## API
+
+Use `#announce:` to trigger an announcement.
+
+Use `#on:do:` or `#on:send:to:` to register subscriptions.
+
+When using `#on:send:to:`, unregistration can be done with `#unregister:`.
+
+## Usage example:
+
+    SystemAnnouncer current
+        on: ClassAdded
+        do: [ :ann | window alert: ann theClass name, ' added' ].!
 
 !Announcer methodsFor: 'announcing'!
 
@@ -109,7 +123,11 @@ Announcer subclass: #SystemAnnouncer
 	instanceVariableNames: ''
 	package: 'Kernel-Announcements'!
 !SystemAnnouncer commentStamp!
-My unique instance #current is the global announcer handling all Amber system-related announces!
+My unique instance is the global announcer handling all Amber system-related announces.
+
+## API
+
+Access to the unique instance is done via `#current`!
 
 SystemAnnouncer class instanceVariableNames: 'current'!
 
@@ -144,6 +162,8 @@ theClass: aClass
 SystemAnnouncement subclass: #ClassAnnouncement
 	instanceVariableNames: 'theClass'
 	package: 'Kernel-Announcements'!
+!ClassAnnouncement commentStamp!
+I am the abstract superclass of class-related announcements.!
 
 !ClassAnnouncement methodsFor: 'accessing'!
 
@@ -172,12 +192,14 @@ ClassAnnouncement subclass: #ClassDefinitionChanged
 	instanceVariableNames: ''
 	package: 'Kernel-Announcements'!
 !ClassDefinitionChanged commentStamp!
-I am emitted when the defintion of a class changes.
+I am emitted when the definition of a class changes.
 See ClassBuilder >> #class:instanceVariableNames:!
 
 ClassAnnouncement subclass: #ClassMigrated
 	instanceVariableNames: 'oldClass'
 	package: 'Kernel-Announcements'!
+!ClassMigrated commentStamp!
+I am emitted when a class is migrated.!
 
 !ClassMigrated methodsFor: 'accessing'!
 
@@ -192,6 +214,8 @@ oldClass: aClass
 ClassAnnouncement subclass: #ClassMoved
 	instanceVariableNames: 'oldPackage'
 	package: 'Kernel-Announcements'!
+!ClassMoved commentStamp!
+I am emitted when a class is moved from one package to another.!
 
 !ClassMoved methodsFor: 'accessing'!
 
@@ -220,6 +244,8 @@ See ClassBuilder >> #renameClass:to:!
 SystemAnnouncement subclass: #MethodAnnouncement
 	instanceVariableNames: 'method'
 	package: 'Kernel-Announcements'!
+!MethodAnnouncement commentStamp!
+I am the abstract superclass of method-related announcements.!
 
 !MethodAnnouncement methodsFor: 'accessing'!
 

+ 20 - 15
st/Kernel-Classes.st

@@ -3,13 +3,14 @@ Object subclass: #Behavior
 	instanceVariableNames: ''
 	package: 'Kernel-Classes'!
 !Behavior commentStamp!
-Behavior is the superclass of all class objects.
+I am the superclass of all class objects.
 
-It defines the protocol for creating instances of a class with `#basicNew` and `#new` (see `boot.js` for class constructors details).
-Instances know about the subclass/superclass relationships between classes, contain the description that instances are created from,
+I define the protocol for creating instances of a class with `#basicNew` and `#new` (see `boot.js` for class constructors details).
+
+My instances know about the subclass/superclass relationships between classes, contain the description that instances are created from,
 and hold the method dictionary that's associated with each class.
 
-Behavior also provides methods for compiling methods, examining the method dictionary, and iterating over the class hierarchy.!
+I also provides methods for compiling methods, examining the method dictionary, and iterating over the class hierarchy.!
 
 !Behavior methodsFor: 'accessing'!
 
@@ -292,10 +293,10 @@ Behavior subclass: #Class
 	instanceVariableNames: ''
 	package: 'Kernel-Classes'!
 !Class commentStamp!
-Class is __the__ class object.
+I am __the__ class object.
 
-Instances are the classes of the system.
-Class creation is done throught a `ClassBuilder`!
+My instances are the classes of the system.
+Class creation is done throught a `ClassBuilder` instance.!
 
 !Class methodsFor: 'accessing'!
 
@@ -388,10 +389,9 @@ Behavior subclass: #Metaclass
 	instanceVariableNames: ''
 	package: 'Kernel-Classes'!
 !Metaclass commentStamp!
-Metaclass is the root of the class hierarchy.
+I am the root of the class hierarchy.
 
-Metaclass instances are metaclasses, one for each real class.
-Metaclass instances have a single instance, which they hold onto, which is the class that they are the metaclass of.!
+My instances are metaclasses, one for each real class, and have a single instance, which they hold onto: the class that they are the metaclass of.!
 
 !Metaclass methodsFor: 'accessing'!
 
@@ -447,9 +447,9 @@ Object subclass: #ClassBuilder
 	instanceVariableNames: ''
 	package: 'Kernel-Classes'!
 !ClassBuilder commentStamp!
-ClassBuilder is responsible for compiling new classes or modifying existing classes in the system.
+I am responsible for compiling new classes or modifying existing classes in the system.
 
-Rather than using ClassBuilder directly to compile a class, use `Class >> subclass:instanceVariableNames:package:`.!
+Rather than using me directly to compile a class, use `Class >> subclass:instanceVariableNames:package:`.!
 
 !ClassBuilder methodsFor: 'accessing'!
 
@@ -668,7 +668,7 @@ Object subclass: #ClassCategoryReader
 	instanceVariableNames: 'class category'
 	package: 'Kernel-Classes'!
 !ClassCategoryReader commentStamp!
-ClassCategoryReader represents a mechanism for retrieving class descriptions stored on a file.!
+I provide a mechanism for retrieving class descriptions stored on a file in the Smalltalk chunk format.!
 
 !ClassCategoryReader methodsFor: 'accessing'!
 
@@ -703,8 +703,9 @@ Object subclass: #ClassCommentReader
 	instanceVariableNames: 'class'
 	package: 'Kernel-Classes'!
 !ClassCommentReader commentStamp!
-ClassCommentReader represents a mechanism for retrieving class comments stored on a file.
-See `ClassCategoryReader` too.!
+I provide a mechanism for retrieving class comments stored on a file.
+
+See also `ClassCategoryReader`.!
 
 !ClassCommentReader methodsFor: 'accessing'!
 
@@ -736,6 +737,10 @@ setComment: aString
 Object subclass: #ClassSorterNode
 	instanceVariableNames: 'theClass level nodes'
 	package: 'Kernel-Classes'!
+!ClassSorterNode commentStamp!
+I provide an algorithm for sorting classes alphabetically.
+
+See [Issue #143](https://github.com/amber-smalltalk/amber/issues/143) on GitHub.!
 
 !ClassSorterNode methodsFor: 'accessing'!
 

+ 9 - 6
st/Kernel-Collections.st

@@ -56,7 +56,7 @@ Object subclass: #Collection
 !Collection commentStamp!
 I am the abstract superclass of all classes that represent a group of elements.
 
-I provide a set of useful methods to the Collectiohn hierarchy such as enumerating and converting methods.!
+I provide a set of useful methods to the Collection hierarchy such as enumerating and converting methods.!
 
 !Collection methodsFor: 'accessing'!
 
@@ -278,10 +278,10 @@ Collection subclass: #IndexableCollection
 	instanceVariableNames: ''
 	package: 'Kernel-Collections'!
 !IndexableCollection commentStamp!
-I am a key-value store, that is,
-it stores values under indexes.
+I am a key-value store collection, that is,
+I store values under indexes.
 
-As a rule of thumb, if a collection has at: and at:put:,
+As a rule of thumb, if a collection has `#at:` and `#at:put:`,
 it is an IndexableCollection.!
 
 !IndexableCollection methodsFor: 'accessing'!
@@ -361,7 +361,7 @@ IndexableCollection subclass: #HashedCollection
 !HashedCollection commentStamp!
 I am a traditional JavaScript object, or a Smalltalk `Dictionary`.
 
-Unlike a `Dictionary`, it can only have strings as keys.!
+Unlike a `Dictionary`, I can only have strings as keys.!
 
 !HashedCollection methodsFor: 'accessing'!
 
@@ -886,7 +886,10 @@ SequenceableCollection subclass: #Array
 	package: 'Kernel-Collections'!
 !Array commentStamp!
 I represent a collection of objects ordered by the collector. The size of arrays is dynamic.
-In Amber, OrderedCollection is an alias for Array.!
+
+I am directly mapped to JavaScript Number.
+
+*Note* In Amber, `OrderedCollection` is an alias for `Array`.!
 
 !Array methodsFor: 'accessing'!
 

+ 51 - 19
st/Kernel-Methods.st

@@ -3,10 +3,28 @@ Object subclass: #BlockClosure
 	instanceVariableNames: ''
 	package: 'Kernel-Methods'!
 !BlockClosure commentStamp!
-A BlockClosure is a lexical closure.
-The JavaScript representation is a function.
+I represent a lexical closure.
+I am is directly mapped to JavaScript Function.
 
-A BlockClosure is evaluated with the `#value*` methods in the 'evaluating' protocol.!
+## API
+
+1. Evaluation
+
+    My instances get evaluated with the `#value*` methods in the 'evaluating' protocol.
+
+    Example: ` [ :x | x + 1 ] value: 3 "Answers 4" `
+
+2. Control structures
+
+    Blocks are used (together with `Boolean`) for control structures (methods in the `controlling` protocol).
+
+    Example: `aBlock whileTrue: [ ... ]`
+
+3. Error handling
+
+    I provide the `#on:do:` method for handling exceptions.
+
+    Example: ` aBlock on: MessageNotUnderstood do: [ :ex | ... ] `!
 
 !BlockClosure methodsFor: 'accessing'!
 
@@ -166,21 +184,22 @@ Object subclass: #CompiledMethod
 	instanceVariableNames: ''
 	package: 'Kernel-Methods'!
 !CompiledMethod commentStamp!
-CompiledMethod hold the source and compiled code of a class method.
+I represent a class method of the system. I hold the source and compiled code of a class method.
 
-You can get a CompiledMethod using `Behavior>>methodAt:`
+## API
+My instances can be accessed using `Behavior >> #methodAt:`
 
-	String methodAt: 'lines'
+    Object methodAt: 'asString'
 
-and read the source code
+Source code access:
 
 	(String methodAt: 'lines') source
 
-See referenced classes:
+Referenced classes:
 
 	(String methodAt: 'lines') referencedClasses
 
-or messages sent from this method:
+Messages sent from an instance:
 	
 	(String methodAt: 'lines') messageSends!
 
@@ -291,10 +310,15 @@ Object subclass: #ForkPool
 	instanceVariableNames: 'poolSize maxPoolSize queue worker'
 	package: 'Kernel-Methods'!
 !ForkPool commentStamp!
-A ForkPool is responsible for handling forked blocks.
+I am responsible for handling forked blocks.
 The pool size sets the maximum concurrent forked blocks.
 
-The default instance is accessed with `ForkPool default`!
+## API
+
+The default instance is accessed with `#default`.
+The maximum concurrent forked blocks can be set with `#maxPoolSize:`.
+
+Forking is done via `BlockClosure >> #fork`!
 
 !ForkPool methodsFor: 'accessing'!
 
@@ -366,11 +390,15 @@ Object subclass: #Message
 	instanceVariableNames: 'selector arguments'
 	package: 'Kernel-Methods'!
 !Message commentStamp!
-Generally, the system does not use instances of Message for efficiency reasons.
+In general, the system does not use instances of me for efficiency reasons.
 However, when a message is not understood by its receiver, the interpreter will make up an instance of it in order to capture the information involved in an actual message transmission.
-This instance is sent it as an argument with the message `doesNotUnderstand:` to the receiver.
+This instance is sent it as an argument with the message `#doesNotUnderstand:` to the receiver.
+
+See boot.js, `messageNotUnderstood` and its counterpart `Object >> #doesNotUnderstand:`
 
-See boot.js, `messageNotUnderstood` and its counterpart `Object>>doesNotUnderstand:`!
+## API
+
+Besides accessing methods, `#sendTo:` provides a convenient way to send a message to an object.!
 
 !Message methodsFor: 'accessing'!
 
@@ -421,6 +449,8 @@ Object subclass: #MessageSend
 !MessageSend commentStamp!
 I encapsulate message sends to objects. Arguments can be either predefined or supplied when the message send is performed. 
 
+## API
+
 Use `#value` to perform a message send with its predefined arguments and `#value:*` if additonal arguments have to supplied.!
 
 !MessageSend methodsFor: 'accessing'!
@@ -501,9 +531,9 @@ Object subclass: #MethodContext
 	instanceVariableNames: ''
 	package: 'Kernel-Methods'!
 !MethodContext commentStamp!
-MethodContext holds all the dynamic state associated with the execution of either a method activation resulting from a message send. That is used to build the call stack while debugging.
+I hold all the dynamic state associated with the execution of either a method activation resulting from a message send. I am used to build the call stack while debugging.
 
-MethodContext instances are JavaScript `SmalltalkMethodContext` objects defined in boot.js!
+My instances are JavaScript `SmalltalkMethodContext` objects defined in `boot.js`.!
 
 !MethodContext methodsFor: 'accessing'!
 
@@ -583,14 +613,16 @@ Object subclass: #NativeFunction
 	instanceVariableNames: ''
 	package: 'Kernel-Methods'!
 !NativeFunction commentStamp!
-NativeFunction is a wrapper around native functions, such as `WebSocket`.
+I am a wrapper around native functions, such as `WebSocket`.
 For 'normal' functions (whose constructor is the JavaScript `Function` object), use `BlockClosure`.
 
-See the class-side `instance creation` methods.
+## API
+
+See the class-side `instance creation` methods for instance creation.
 
 Created instances will most probably be instance of `JSObjectProxy`.
 
-Usage example:
+## Usage example:
 
 	| ws |
 	ws := NativeFunction constructor: 'WebSocket' value: 'ws://localhost'.

+ 85 - 47
st/Kernel-Objects.st

@@ -3,11 +3,11 @@ nil subclass: #Object
 	instanceVariableNames: ''
 	package: 'Kernel-Objects'!
 !Object commentStamp!
-*Object is the root of the Smalltalk class system*. All classes in the system are subclasses of Object.
+**I am the root of the Smalltalk class system**. All classes in the system are subclasses of me.
 
-Object provides default behavior common to all normal objects, such as:
+I provide default behavior common to all normal objects, such as:
 
-- access
+- accessing
 - copying
 - comparison
 - error handling
@@ -16,11 +16,11 @@ Object provides default behavior common to all normal objects, such as:
 
 Also utility messages that all objects should respond to are defined here.
 
-Object has no instance variable.
+I have no instance variable.
 
 ##Access
 
-Instance variables can be accessed with `#instVarAt:` and `#instVarAt:put:`. `Object >> instanceVariableNames` answers a collection of all instance variable names.
+Instance variables can be accessed with `#instVarAt:` and `#instVarAt:put:`. `#instanceVariableNames` answers a collection of all instance variable names.
 Accessing JavaScript properties of an object is done through `#basicAt:`, `#basicAt:put:` and `basicDelete:`.
 
 ##Copying
@@ -30,7 +30,7 @@ The hook method `#postCopy` can be overriden in subclasses to copy fields as nec
 
 ##Comparison
 
-Objects understand equality `#=` and identity `#==` comparison.
+I understand equality `#=` and identity `#==` comparison.
 
 ##Error handling
 
@@ -354,10 +354,15 @@ Object subclass: #Boolean
 	instanceVariableNames: ''
 	package: 'Kernel-Objects'!
 !Boolean commentStamp!
-Boolean wraps the JavaScript `Boolean()` constructor. The `true` and `false` objects are the JavaScript boolean objects.
+I define the protocol for logic testing operations and conditional control structures for the logical values (see the `controlling` protocol).
 
-Boolean defines the protocol for logic testing operations and conditional control structures for the logical values.
-Boolean instances are weither `true` or `false`.!
+I have two instances, `true` and `false`.
+
+I am directly mapped to JavaScript Boolean. The `true` and `false` objects are the JavaScript boolean objects.
+
+## Usage Example:
+
+    aBoolean not ifTrue: [ ... ] ifFalse: [ ... ]!
 
 !Boolean methodsFor: 'comparing'!
 
@@ -478,10 +483,18 @@ Object subclass: #Date
 	instanceVariableNames: ''
 	package: 'Kernel-Objects'!
 !Date commentStamp!
-The Date class is used to work with dates and times. Therefore `Date today` and `Date now` are both valid in
+I am used to work with both dates and times. Therefore `Date today` and `Date now` are both valid in
 Amber and answer the same date object.
 
-Date wraps the `Date()` JavaScript constructor, and Smalltalk date objects are JavaScript date objects.!
+Date directly maps to the `Date()` JavaScript constructor, and Amber date objects are JavaScript date objects.
+
+## API
+
+The class-side `instance creation` protocol contains some convenience methods for creating date/time objects such as `#fromSeconds:`.
+
+Arithmetic and comparison is supported (see the `comparing` and `arithmetic` protocols).
+
+The `converting` protocol provides convenience methods for various convertions (to numbers, strings, etc.).!
 
 !Date methodsFor: 'accessing'!
 
@@ -663,7 +676,9 @@ Object subclass: #Environment
 	instanceVariableNames: ''
 	package: 'Kernel-Objects'!
 !Environment commentStamp!
-Abstract class defining common behavior for local and remote environments!
+I provide an unified entry point to manipulate Amber packages, classes and methods.
+
+Typical use cases include IDEs, remote access and restricting browsing.!
 
 !Environment methodsFor: 'accessing'!
 
@@ -818,10 +833,12 @@ Object subclass: #JSObjectProxy
 	instanceVariableNames: 'jsObject'
 	package: 'Kernel-Objects'!
 !JSObjectProxy commentStamp!
-JSObjectProxy handles sending messages to JavaScript object, therefore accessing JavaScript objects from Amber is transparent.
-JSOjbectProxy makes intensive use of `#doesNotUnderstand:`.
+I handle sending messages to JavaScript objects, making  JavaScript object accessing from Amber fully transparent.
+My instances make intensive use of `#doesNotUnderstand:`.
+
+My instances are automatically created by Amber whenever a message is sent to a JavaScript object.
 
-## Examples
+## Usage examples
 
 JSObjectProxy objects are instanciated by Amber when a Smalltalk message is sent to a JavaScript object.
 
@@ -829,7 +846,7 @@ JSObjectProxy objects are instanciated by Amber when a Smalltalk message is sent
 	window inspect.
 	(window jQuery: 'body') append: 'hello world'
 
-Smalltalk messages sends are converted to JavaScript function calls or object property access _(in this order)_. If n one of them match, a `MessageNotUnderstood` error will be thrown.
+Amber messages sends are converted to JavaScript function calls or object property access _(in this order)_. If n one of them match, a `MessageNotUnderstood` error will be thrown.
 
 ## Message conversion rules
 
@@ -962,13 +979,14 @@ Object subclass: #Number
 	instanceVariableNames: ''
 	package: 'Kernel-Objects'!
 !Number commentStamp!
-Number holds the most general methods for dealing with numbers.
-Number is directly mapped to JavaScript Number.
+I am the Amber representation for all numbers.
+I am directly mapped to JavaScript Number.
 
-Most arithmetic methods like `#+` `#/` `#-` `#max:` are directly inlined into javascript.
+## API
 
-##Enumerating
-A Number can be used to evaluate a Block a fixed number of times:
+I provide all necessary methods for arithmetic operations, comparison, conversion and so on with numbers.
+
+My instances can also be used to evaluate a block a fixed number of times:
 
 	5 timesRepeat: [Transcript show: 'This will be printed 5 times'; cr].
 	
@@ -1238,6 +1256,12 @@ pi
 Object subclass: #Organizer
 	instanceVariableNames: ''
 	package: 'Kernel-Objects'!
+!Organizer commentStamp!
+I represent categorization information. 
+
+## API
+
+Use `#addElement:` and `#removeElement:` to manipulate instances.!
 
 !Organizer methodsFor: 'accessing'!
 
@@ -1256,6 +1280,8 @@ removeElement: anObject
 Organizer subclass: #ClassOrganizer
 	instanceVariableNames: ''
 	package: 'Kernel-Objects'!
+!ClassOrganizer commentStamp!
+I am an organizer specific to classes. I hold method categorization information for classes.!
 
 !ClassOrganizer methodsFor: 'accessing'!
 
@@ -1284,29 +1310,29 @@ theClass
 Organizer subclass: #PackageOrganizer
 	instanceVariableNames: ''
 	package: 'Kernel-Objects'!
+!PackageOrganizer commentStamp!
+I am an organizer specific to packages. I hold classes categorization information.!
 
 Object subclass: #Package
 	instanceVariableNames: 'commitPathJs commitPathSt'
 	package: 'Kernel-Objects'!
 !Package commentStamp!
-A Package is similar to a "class category" typically found in other Smalltalks like Pharo or Squeak. Amber does not have class categories anymore, it had in the beginning but now each class in the system knows which package it belongs to.
+I am similar to a "class category" typically found in other Smalltalks like Pharo or Squeak. Amber does not have class categories anymore, it had in the beginning but now each class in the system knows which package it belongs to.
 
-A Package has a name, an Array of "requires", a comment and a Dictionary with other optional key value attributes. A Package can also be queried for its classes, but it will then resort to a reverse scan of all classes to find them.
-Packages are manipulated through "Smalltalk current", like for example finding one based on a name:
+Each package has a name and can be queried for its classes, but it will then resort to a reverse scan of all classes to find them.
 
-	Smalltalk current packageAt: 'Kernel'
+## API
 
-...but you can also use:
+Packages are manipulated through "Smalltalk current", like for example finding one based on a name or with `Package class >> #name` directly:
 
-	Package named: 'Kernel'
+    Smalltalk current packageAt: 'Kernel'
+    Package named: 'Kernel'
 
-A Package differs slightly from a Monticello package which can span multiple class categories using a naming convention based on hyphenation. But just as in Monticello a Package supports "class extensions" so a Package
-can define behaviors in foreign classes using a naming convention for method categories where the category starts with an asterisk and then the name of the owning package follows. This can easily be seen in for example class
-String where the method category "*IDE" defines #inspectOn: which thus is a method belonging to the IDE package.
+A package differs slightly from a Monticello package which can span multiple class categories using a naming convention based on hyphenation. But just as in Monticello a package supports "class extensions" so a package can define behaviors in foreign classes using a naming convention for method categories where the category starts with an asterisk and then the name of the owning package follows.
 
 You can fetch a package from the server:
 
-	Package fetch: 'Additional-Examples'!
+	Package load: 'Additional-Examples'!
 
 !Package methodsFor: 'accessing'!
 
@@ -1463,8 +1489,11 @@ Object subclass: #Point
 	instanceVariableNames: 'x y'
 	package: 'Kernel-Objects'!
 !Point commentStamp!
-A `Point` represents an x-y pair of numbers usually designating a geometric coordinate.
-Points are traditionally created using the binary `#@` message to a number:
+I represent an x-y pair of numbers usually designating a geometric coordinate.
+
+## API
+
+Instances are traditionally created using the binary `#@` message to a number:
 
 	100@120
 
@@ -1476,11 +1505,9 @@ Points can then be arithmetically manipulated:
 
 	(100@100) * 2
 
-**NOTE:** Creating a Point with a negative y-value will need a space after `@` in order to avoid a parsing error:
+**NOTE:** Creating a point with a negative y-value will need a space after `@` in order to avoid a parsing error:
 
-	100@ -100 "but 100@-100 would not parse"
-
-Amber does not have much behavior in this class out-of-the-box.!
+	100@ -100 "but 100@-100 would not parse"!
 
 !Point methodsFor: 'accessing'!
 
@@ -1564,7 +1591,11 @@ Object subclass: #Random
 	instanceVariableNames: ''
 	package: 'Kernel-Objects'!
 !Random commentStamp!
-`Random` is a random number generator and is implemented as a trivial wrapper around javascript `Math.random()` and is used like this:
+I an used to generate a random number and I am implemented as a trivial wrapper around javascript `Math.random()`.
+
+## API
+
+The typical use case it to use the `#next` method like the following:
 
 	Random new next
 
@@ -1572,11 +1603,11 @@ This will return a float x where x < 1 and x > 0. If you want a random integer f
 
 	10 atRandom
 
-...and if you want a random number in a specific interval this also works:
+A random number in a specific interval can be obtained with the following:
 
 	(3 to: 7) atRandom
 
-...but be aware that `#to:` does not create an Interval as in other Smalltalk implementations but in fact an `Array` of numbers, so it's better to use:
+Be aware that `#to:` does not create an Interval as in other Smalltalk implementations but in fact an `Array` of numbers, so it's better to use:
 
 	5 atRandom + 2
 
@@ -1584,7 +1615,7 @@ Since `#atRandom` is implemented in `SequencableCollection` you can easy pick an
 
 	#('a' 'b' 'c') atRandom
 
-...or perhaps a letter from a `String`:
+As well as letter from a `String`:
 
 	'abc' atRandom
 
@@ -1604,8 +1635,11 @@ Object subclass: #Smalltalk
 	instanceVariableNames: ''
 	package: 'Kernel-Objects'!
 !Smalltalk commentStamp!
-Smalltalk has only one instance, accessed with `Smalltalk current`.
-It represents the global JavaScript variable `smalltalk` declared in `js/boot.js`.
+I represent the global JavaScript variable `smalltalk` declared in `js/boot.js`.
+
+## API
+
+I have only one instance, accessed with class-side method `#current`.
 
 The `smalltalk` object holds all class and packages defined in the system.
 
@@ -1627,7 +1661,7 @@ __note:__ classes and packages are accessed using strings, not symbols
 
 ## Parsing
 
-The `#parse:` method is used to parse Smalltalk source code.
+The `#parse:` method is used to parse Amber source code.
 It requires the `Compiler` package and the `js/parser.js` parser file in order to work!
 
 !Smalltalk methodsFor: 'accessing'!
@@ -1783,7 +1817,9 @@ Object subclass: #Timeout
 	instanceVariableNames: 'rawTimeout'
 	package: 'Kernel-Objects'!
 !Timeout commentStamp!
-I am wrapping the returns from set{Timeout,Interval}.
+I am wrapping the returns from `set{Timeout,Interval}`.
+
+## Motivation
 
 Number suffices in browsers, but node.js returns an object.!
 
@@ -1819,9 +1855,11 @@ Object subclass: #UndefinedObject
 	instanceVariableNames: ''
 	package: 'Kernel-Objects'!
 !UndefinedObject commentStamp!
-UndefinedObject describes the behavior of its sole instance, `nil`. `nil` represents a prior value for variables that have not been initialized, or for results which are meaningless.
+I describe the behavior of my sole instance, `nil`. `nil` represents a prior value for variables that have not been initialized, or for results which are meaningless.
+
+`nil` is the Smalltalk equivalent of the `undefined` JavaScript object.
 
-`nil` is the Smalltalk representation of the `undefined` JavaScript object.!
+__note:__ When sending messages to the `undefined` JavaScript object, it will be replaced by `nil`.!
 
 !UndefinedObject methodsFor: 'class creation'!