Browse Source

Improved class comments

Nicolas Petton 11 years ago
parent
commit
cd60780111

BIN
images/magnitude.png


BIN
images/testGreen.png


BIN
images/testNotRun.png


BIN
images/testRed.png


BIN
images/testYellow.png


BIN
images/test_old.png


+ 5 - 5
js/Canvas.js

@@ -1,6 +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.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\x0a## API\x0a\x0aMy instances are used as the argument of the `#renderOn:` method of `Widget` objects.\x0a\x0aThe `#with:` method is used to compose HTML, nesting tags. `#with:` can take a `TagBrush`, a `String`, a `BlockClosure` or a `Widget` as argument.\x0a\x0a## Usage example:\x0a\x0a    aCanvas a \x0a        with: [ aCanvas span with: 'click me' ];\x0a        onClick: [ window alert: 'clicked!' ]\x0a"
 smalltalk.addMethod(
 smalltalk.method({
 selector: "a",
@@ -2192,7 +2192,7 @@ smalltalk.HTMLCanvas.klass);
 
 
 smalltalk.addClass('HTMLSnippet', smalltalk.Object, ['snippets'], 'Canvas');
-smalltalk.HTMLSnippet.comment="HTMLSnippet instance is the registry of html snippets.\x0aHTMLSnippet current is the public singleton instance.\x0a\x0aAt the beginning, it scans the document for any html elements\x0awith 'data-snippet=\x22foo\x22' attribute and takes them off the document,\x0aremembering them in the store under the specified name.\x0aIt also install method #foo into HTMLCanvas dynamically.\x0a\x0aEvery html snippet should mark a 'caret', a place where contents\x0acan be inserted, by 'data-snippet=\x22*\x22' (a special name for caret).\x0aFor example:\x0a\x0a<li data-snippet='menuelement' class='...'><a data-snippet='*'></a></li>\x0a\x0adefines a list element with a link inside; the link itself is marked as a caret.\x0a\x0aYou can later issue\x0a\x0ahtml menuelement href: '/foo'; with: 'A foo'\x0a\x0ato insert the whole snippet and directly manipulate the caret, so it renders:\x0a\x0a<li class='...'><a href='/foo'>A foo</a></li>\x0a\x0aFor a self-careting tags (not very useful, but you do not need to fill class etc.\x0ayou can use\x0a\x0a<div class='lots of classes' attr1='one' attr2='two' data-snippet='*bar'></div>\x0a\x0aand in code later do:\x0a\x0ahtml bar with: [ xxx ]\x0a\x0ato render\x0a\x0a<div class='lots of classes' attr1='one' attr2='two'>...added by xxx...</div>"
+smalltalk.HTMLSnippet.comment="My sole instance is the registry of html snippets.\x0a`HTMLSnippet current` is the public singleton instance.\x0a\x0aOn startup, it scans the document for any html elements\x0awith `'data-snippet=\x22foo\x22'` attribute and takes them off the document,\x0aremembering them in the store under the specified name.\x0aIt also install method #foo into HTMLCanvas dynamically.\x0a\x0aEvery html snippet should mark a 'caret', a place where contents\x0acan be inserted, by 'data-snippet=\x22*\x22' (a special name for caret).\x0aFor example:\x0a\x0a`<li data-snippet='menuelement' class='...'><a data-snippet='*'></a></li>`\x0a\x0adefines a list element with a link inside; the link itself is marked as a caret.\x0a\x0aYou can later issue\x0a\x0a`html menuelement href: '/foo'; with: 'A foo'`\x0a\x0ato insert the whole snippet and directly manipulate the caret, so it renders:\x0a\x0a`<li class='...'><a href='/foo'>A foo</a></li>`\x0a\x0aFor a self-careting tags (not very useful, but you do not need to fill class etc.\x0ayou can use\x0a\x0a`<div class='lots of classes' attr1='one' attr2='two' data-snippet='*bar'></div>`\x0a\x0aand in code later do:\x0a\x0a`html bar with: [ xxx ]`\x0a\x0ato render\x0a\x0a`<div class='lots of classes' attr1='one' attr2='two'>...added by xxx...</div>`"
 smalltalk.addMethod(
 smalltalk.method({
 selector: "initializeFromJQuery:",
@@ -2441,7 +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.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, a `Widget` or 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:",
@@ -3580,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\x0aThe need for a specific class comes from IE compatibility problems."
+smalltalk.StyleTag.comment="I'm a `<style>` tag use to inline CSS or load a stylesheet.\x0a\x0a## Motivation\x0a\x0aThe need for a specific class comes from Internet Explorer compatibility issues."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "with:",
@@ -3628,7 +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.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).\x0a\x0aTo add a widget to the page, the convenience method `#appendToJQuery:` is very useful.\x0a\x0aExemple: \x0a\x0a    Counter new appendToJQuery: 'body' asJQuery"
 smalltalk.addMethod(
 smalltalk.method({
 selector: "appendToBrush:",

+ 12 - 2
js/Helios-Core.deploy.js

@@ -1763,7 +1763,6 @@ fn: function (html){
 var self=this;
 return smalltalk.withContext(function($ctx1) { 
 var $1,$2,$3,$4;
-_st(self)._registerBindings();
 $1=_st(html)._div();
 _st($1)._class_("hl_widget");
 $2=_st($1)._yourself();
@@ -1783,7 +1782,7 @@ return smalltalk.withContext(function($ctx2) {
 return _st(_st(_st(self)._wrapper())._asJQuery())._addClass_(_st(self)._focusClass());
 }, function($ctx2) {$ctx2.fillBlock({},$ctx1)})}));
 return self}, function($ctx1) {$ctx1.fill(self,"renderOn:",{html:html},smalltalk.HLFocusableWidget)})},
-messageSends: ["registerBindings", "class:", "div", "yourself", "with:", "renderContentOn:", "at:put:", "onBlur:", "removeClass:", "focusClass", "asJQuery", "wrapper", "onFocus:", "addClass:"]}),
+messageSends: ["class:", "div", "yourself", "with:", "renderContentOn:", "at:put:", "onBlur:", "removeClass:", "focusClass", "asJQuery", "wrapper", "onFocus:", "addClass:"]}),
 smalltalk.HLFocusableWidget);
 
 
@@ -3232,6 +3231,17 @@ return true;
 messageSends: []}),
 smalltalk.HLSUnit.klass);
 
+smalltalk.addMethod(
+smalltalk.method({
+selector: "tabClass",
+fn: function (){
+var self=this;
+return smalltalk.withContext(function($ctx1) { 
+return "sunit";
+}, function($ctx1) {$ctx1.fill(self,"tabClass",{},smalltalk.HLSUnit.klass)})},
+messageSends: []}),
+smalltalk.HLSUnit.klass);
+
 smalltalk.addMethod(
 smalltalk.method({
 selector: "tabLabel",

+ 22 - 4
js/Helios-Core.js

@@ -1476,7 +1476,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.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.\x0a\x0a## API\x0a\x0a1. Rendering\x0a\x0a    Instead of overriding `#renderOn:` as with other Widget subclasses, my subclasses should override `#renderContentOn:`.\x0a\x0a2. Refreshing\x0a\x0a    To re-render a widget, use `#refresh`.\x0a\x0a3. Key bindings registration and tabs\x0a\x0a    When displayed as a tab, the widget has a chance to register keybindings with the `#registerBindingsOn:` hook method.\x0a    \x0a4. Unregistration\x0a\x0a    When a widget has subscribed to announcements or other actions that need to be cleared when closing the tab, the hook method `#unregister` will be called by helios.\x0a\x0a5. Tabs\x0a\x0a   To enable a widget class to be open as a tab, override the class-side `#canBeOpenAsTab` method to answer `true`. `#tabClass` and `#tabPriority` can be overridden too to respectively change the css class of the tab and the order of tabs in the main menu.\x0a\x0a6. Command execution\x0a\x0a    An helios command (instance of `HLCommand` or one of its subclass) can be executed with `#execute:`."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "alert:",
@@ -1834,6 +1834,7 @@ smalltalk.HLWidget.klass);
 
 
 smalltalk.addClass('HLConfirmation', smalltalk.HLWidget, ['confirmationString', 'actionBlock', 'cancelBlock'], 'Helios-Core');
+smalltalk.HLConfirmation.comment="I display confirmation messages. \x0a\x0aInstead of creating an instance directly, use `HLWidget >> #confirm:ifTrue:`."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "actionBlock",
@@ -2137,6 +2138,7 @@ smalltalk.HLConfirmation);
 
 
 smalltalk.addClass('HLRequest', smalltalk.HLConfirmation, ['input', 'value'], 'Helios-Core');
+smalltalk.HLRequest.comment="I display a modal window requesting user input.\x0a\x0aInstead of creating instances manually, use `HLWidget >> #request:do:` and `#request:value:do:`."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "confirm",
@@ -2230,6 +2232,7 @@ smalltalk.HLRequest);
 
 
 smalltalk.addClass('HLFocusableWidget', smalltalk.HLWidget, [], 'Helios-Core');
+smalltalk.HLFocusableWidget.comment="I am a widget that can be focused.\x0a\x0a## API \x0a\x0aInstead of overriding `#renderOn:` as with other `Widget` subclasses, my subclasses should override `#renderContentOn:`.\x0a\x0aTo bring the focus to the widget, use the `#focus` method."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "blur",
@@ -2338,7 +2341,6 @@ fn: function (html){
 var self=this;
 return smalltalk.withContext(function($ctx1) { 
 var $1,$2,$3,$4;
-_st(self)._registerBindings();
 $1=_st(html)._div();
 _st($1)._class_("hl_widget");
 $2=_st($1)._yourself();
@@ -2359,8 +2361,8 @@ return _st(_st(_st(self)._wrapper())._asJQuery())._addClass_(_st(self)._focusCla
 }, function($ctx2) {$ctx2.fillBlock({},$ctx1)})}));
 return self}, function($ctx1) {$ctx1.fill(self,"renderOn:",{html:html},smalltalk.HLFocusableWidget)})},
 args: ["html"],
-source: "renderOn: html\x0a\x09self registerBindings.\x0a    \x0a    wrapper := html div \x0a    \x09class: 'hl_widget';\x0a\x09\x09yourself.\x0a\x09\x09\x0a       wrapper with: [ self renderContentOn: html ].\x0a\x09\x0a\x09wrapper\x0a\x09\x09at: 'tabindex' put: '0';\x0a\x09\x09onBlur: [ self wrapper asJQuery removeClass: self focusClass ];\x0a        onFocus: [ self wrapper asJQuery addClass: self focusClass ]",
-messageSends: ["registerBindings", "class:", "div", "yourself", "with:", "renderContentOn:", "at:put:", "onBlur:", "removeClass:", "focusClass", "asJQuery", "wrapper", "onFocus:", "addClass:"],
+source: "renderOn: html\x0a    wrapper := html div \x0a    \x09class: 'hl_widget';\x0a\x09\x09yourself.\x0a\x09\x09\x0a       wrapper with: [ self renderContentOn: html ].\x0a\x09\x0a\x09wrapper\x0a\x09\x09at: 'tabindex' put: '0';\x0a\x09\x09onBlur: [ self wrapper asJQuery removeClass: self focusClass ];\x0a        onFocus: [ self wrapper asJQuery addClass: self focusClass ]",
+messageSends: ["class:", "div", "yourself", "with:", "renderContentOn:", "at:put:", "onBlur:", "removeClass:", "focusClass", "asJQuery", "wrapper", "onFocus:", "addClass:"],
 referencedClasses: []
 }),
 smalltalk.HLFocusableWidget);
@@ -4206,6 +4208,22 @@ referencedClasses: []
 }),
 smalltalk.HLSUnit.klass);
 
+smalltalk.addMethod(
+smalltalk.method({
+selector: "tabClass",
+category: 'accessing',
+fn: function (){
+var self=this;
+return smalltalk.withContext(function($ctx1) { 
+return "sunit";
+}, function($ctx1) {$ctx1.fill(self,"tabClass",{},smalltalk.HLSUnit.klass)})},
+args: [],
+source: "tabClass\x0a\x09^ 'sunit'",
+messageSends: [],
+referencedClasses: []
+}),
+smalltalk.HLSUnit.klass);
+
 smalltalk.addMethod(
 smalltalk.method({
 selector: "tabLabel",

+ 33 - 0
js/Kernel-Objects.deploy.js

@@ -1503,6 +1503,17 @@ return $1;
 messageSends: ["new:"]}),
 smalltalk.Date.klass);
 
+smalltalk.addMethod(
+smalltalk.method({
+selector: "heliosClass",
+fn: function (){
+var self=this;
+return smalltalk.withContext(function($ctx1) { 
+return "magnitude";
+}, function($ctx1) {$ctx1.fill(self,"heliosClass",{},smalltalk.Date.klass)})},
+messageSends: []}),
+smalltalk.Date.klass);
+
 smalltalk.addMethod(
 smalltalk.method({
 selector: "millisecondsToRun:",
@@ -2909,6 +2920,17 @@ messageSends: []}),
 smalltalk.Number);
 
 
+smalltalk.addMethod(
+smalltalk.method({
+selector: "heliosClass",
+fn: function (){
+var self=this;
+return smalltalk.withContext(function($ctx1) { 
+return "magnitude";
+}, function($ctx1) {$ctx1.fill(self,"heliosClass",{},smalltalk.Number.klass)})},
+messageSends: []}),
+smalltalk.Number.klass);
+
 smalltalk.addMethod(
 smalltalk.method({
 selector: "pi",
@@ -3548,6 +3570,17 @@ messageSends: []}),
 smalltalk.Point);
 
 
+smalltalk.addMethod(
+smalltalk.method({
+selector: "heliosClass",
+fn: function (){
+var self=this;
+return smalltalk.withContext(function($ctx1) { 
+return "magnitude";
+}, function($ctx1) {$ctx1.fill(self,"heliosClass",{},smalltalk.Point.klass)})},
+messageSends: []}),
+smalltalk.Point.klass);
+
 smalltalk.addMethod(
 smalltalk.method({
 selector: "x:y:",

+ 48 - 0
js/Kernel-Objects.js

@@ -2101,6 +2101,22 @@ referencedClasses: []
 }),
 smalltalk.Date.klass);
 
+smalltalk.addMethod(
+smalltalk.method({
+selector: "heliosClass",
+category: 'helios',
+fn: function (){
+var self=this;
+return smalltalk.withContext(function($ctx1) { 
+return "magnitude";
+}, function($ctx1) {$ctx1.fill(self,"heliosClass",{},smalltalk.Date.klass)})},
+args: [],
+source: "heliosClass\x0a\x09^ 'magnitude'",
+messageSends: [],
+referencedClasses: []
+}),
+smalltalk.Date.klass);
+
 smalltalk.addMethod(
 smalltalk.method({
 selector: "millisecondsToRun:",
@@ -3981,6 +3997,22 @@ referencedClasses: []
 smalltalk.Number);
 
 
+smalltalk.addMethod(
+smalltalk.method({
+selector: "heliosClass",
+category: 'helios',
+fn: function (){
+var self=this;
+return smalltalk.withContext(function($ctx1) { 
+return "magnitude";
+}, function($ctx1) {$ctx1.fill(self,"heliosClass",{},smalltalk.Number.klass)})},
+args: [],
+source: "heliosClass\x0a\x09^ 'magnitude'",
+messageSends: [],
+referencedClasses: []
+}),
+smalltalk.Number.klass);
+
 smalltalk.addMethod(
 smalltalk.method({
 selector: "pi",
@@ -4840,6 +4872,22 @@ referencedClasses: []
 smalltalk.Point);
 
 
+smalltalk.addMethod(
+smalltalk.method({
+selector: "heliosClass",
+category: 'helios',
+fn: function (){
+var self=this;
+return smalltalk.withContext(function($ctx1) { 
+return "magnitude";
+}, function($ctx1) {$ctx1.fill(self,"heliosClass",{},smalltalk.Point.klass)})},
+args: [],
+source: "heliosClass\x0a\x09^ 'magnitude'",
+messageSends: [],
+referencedClasses: []
+}),
+smalltalk.Point.klass);
+
 smalltalk.addMethod(
 smalltalk.method({
 selector: "x:y:",

+ 26 - 14
st/Canvas.st

@@ -7,7 +7,11 @@ 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.
+## API
+
+My instances are used as the argument of the `#renderOn:` method of `Widget` objects.
+
+The `#with:` method is used to compose HTML, nesting tags. `#with:` can take a `TagBrush`, a `String`, a `BlockClosure` or a `Widget` as argument.
 
 ## Usage example:
 
@@ -532,11 +536,11 @@ Object subclass: #HTMLSnippet
 	instanceVariableNames: 'snippets'
 	package: 'Canvas'!
 !HTMLSnippet commentStamp!
-HTMLSnippet instance is the registry of html snippets.
-HTMLSnippet current is the public singleton instance.
+My sole instance is the registry of html snippets.
+`HTMLSnippet current` is the public singleton instance.
 
-At the beginning, it scans the document for any html elements
-with 'data-snippet="foo"' attribute and takes them off the document,
+On startup, it scans the document for any html elements
+with `'data-snippet="foo"'` attribute and takes them off the document,
 remembering them in the store under the specified name.
 It also install method #foo into HTMLCanvas dynamically.
 
@@ -544,30 +548,30 @@ Every html snippet should mark a 'caret', a place where contents
 can be inserted, by 'data-snippet="*"' (a special name for caret).
 For example:
 
-<li data-snippet='menuelement' class='...'><a data-snippet='*'></a></li>
+`<li data-snippet='menuelement' class='...'><a data-snippet='*'></a></li>`
 
 defines a list element with a link inside; the link itself is marked as a caret.
 
 You can later issue
 
-html menuelement href: '/foo'; with: 'A foo'
+`html menuelement href: '/foo'; with: 'A foo'`
 
 to insert the whole snippet and directly manipulate the caret, so it renders:
 
-<li class='...'><a href='/foo'>A foo</a></li>
+`<li class='...'><a href='/foo'>A foo</a></li>`
 
 For a self-careting tags (not very useful, but you do not need to fill class etc.
 you can use
 
-<div class='lots of classes' attr1='one' attr2='two' data-snippet='*bar'></div>
+`<div class='lots of classes' attr1='one' attr2='two' data-snippet='*bar'></div>`
 
 and in code later do:
 
-html bar with: [ xxx ]
+`html bar with: [ xxx ]`
 
 to render
 
-<div class='lots of classes' attr1='one' attr2='two'>...added by xxx...</div>!
+`<div class='lots of classes' attr1='one' attr2='two'>...added by xxx...</div>`!
 
 !HTMLSnippet methodsFor: 'accessing'!
 
@@ -671,7 +675,7 @@ All tags but `<style>` are instances of me (see the `StyleBrush` class).
 
 1. Nesting
 
-    Use `#with:` to nest tags. `#with:` can take aString, `TagBrush` instance of block closure as parameter.
+    Use `#with:` to nest tags. `#with:` can take aString, `TagBrush` instance, a `Widget` or block closure as parameter.
 
     Example: `aTag with: aString with: aCanvas div`
 
@@ -1014,7 +1018,9 @@ TagBrush subclass: #StyleTag
 !StyleTag commentStamp!
 I'm a `<style>` tag use to inline CSS or load a stylesheet.
 
-The need for a specific class comes from IE compatibility problems.!
+## Motivation
+
+The need for a specific class comes from Internet Explorer compatibility issues.!
 
 !StyleTag methodsFor: 'adding'!
 
@@ -1040,7 +1046,13 @@ 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).!
+Use `#renderContentOn:` to build HTML. (See `HTMLCanvas` and `TagBrush` classes for more about building HTML).
+
+To add a widget to the page, the convenience method `#appendToJQuery:` is very useful.
+
+Exemple: 
+
+    Counter new appendToJQuery: 'body' asJQuery!
 
 !Widget methodsFor: 'adding'!
 

+ 47 - 3
st/Helios-Core.st

@@ -519,7 +519,33 @@ Widget subclass: #HLWidget
 !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.!
+I provide common methods, additional behavior to widgets useful for Helios, like dialog creation, command execution and tab creation.
+
+## API
+
+1. Rendering
+
+    Instead of overriding `#renderOn:` as with other Widget subclasses, my subclasses should override `#renderContentOn:`.
+
+2. Refreshing
+
+    To re-render a widget, use `#refresh`.
+
+3. Key bindings registration and tabs
+
+    When displayed as a tab, the widget has a chance to register keybindings with the `#registerBindingsOn:` hook method.
+    
+4. Unregistration
+
+    When a widget has subscribed to announcements or other actions that need to be cleared when closing the tab, the hook method `#unregister` will be called by helios.
+
+5. Tabs
+
+   To enable a widget class to be open as a tab, override the class-side `#canBeOpenAsTab` method to answer `true`. `#tabClass` and `#tabPriority` can be overridden too to respectively change the css class of the tab and the order of tabs in the main menu.
+
+6. Command execution
+
+    An helios command (instance of `HLCommand` or one of its subclass) can be executed with `#execute:`.!
 
 !HLWidget methodsFor: 'accessing'!
 
@@ -629,6 +655,10 @@ canBeOpenAsTab
 HLWidget subclass: #HLConfirmation
 	instanceVariableNames: 'confirmationString actionBlock cancelBlock'
 	package: 'Helios-Core'!
+!HLConfirmation commentStamp!
+I display confirmation messages. 
+
+Instead of creating an instance directly, use `HLWidget >> #confirm:ifTrue:`.!
 
 !HLConfirmation methodsFor: 'accessing'!
 
@@ -727,6 +757,10 @@ setupKeyBindings
 HLConfirmation subclass: #HLRequest
 	instanceVariableNames: 'input value'
 	package: 'Helios-Core'!
+!HLRequest commentStamp!
+I display a modal window requesting user input.
+
+Instead of creating instances manually, use `HLWidget >> #request:do:` and `#request:value:do:`.!
 
 !HLRequest methodsFor: 'accessing'!
 
@@ -760,6 +794,14 @@ renderMainOn: html
 HLWidget subclass: #HLFocusableWidget
 	instanceVariableNames: ''
 	package: 'Helios-Core'!
+!HLFocusableWidget commentStamp!
+I am a widget that can be focused.
+
+## API 
+
+Instead of overriding `#renderOn:` as with other `Widget` subclasses, my subclasses should override `#renderContentOn:`.
+
+To bring the focus to the widget, use the `#focus` method.!
 
 !HLFocusableWidget methodsFor: 'accessing'!
 
@@ -787,8 +829,6 @@ renderContentOn: html
 !
 
 renderOn: html
-	self registerBindings.
-    
     wrapper := html div 
     	class: 'hl_widget';
 		yourself.
@@ -1433,6 +1473,10 @@ HLWidget subclass: #HLSUnit
 
 !HLSUnit class methodsFor: 'accessing'!
 
+tabClass
+	^ 'sunit'
+!
+
 tabLabel
 	^ 'SUnit'
 !

+ 18 - 0
st/Kernel-Objects.st

@@ -668,6 +668,12 @@ printOn: aStream
 	aStream nextPutAll: self asString
 ! !
 
+!Date class methodsFor: 'helios'!
+
+heliosClass
+	^ 'magnitude'
+! !
+
 !Date class methodsFor: 'instance creation'!
 
 fromMilliseconds: aNumber
@@ -1324,6 +1330,12 @@ positive
 	^ self >= 0
 ! !
 
+!Number class methodsFor: 'helios'!
+
+heliosClass
+	^ 'magnitude'
+! !
+
 !Number class methodsFor: 'instance creation'!
 
 pi
@@ -1655,6 +1667,12 @@ translateBy: delta
 	^(delta x + x) @ (delta y + y)
 ! !
 
+!Point class methodsFor: 'helios'!
+
+heliosClass
+	^ 'magnitude'
+! !
+
 !Point class methodsFor: 'instance creation'!
 
 x: aNumber y: anotherNumber