completing api docs

adding the missing paragraphs and some formatting

docs/api/index.md

@@ -34,7 +34,28 @@ The `div` reference can be either:
 
 ## Compiler usage and options
 
-TBD
+This module compiles a template and returns the JS compiled string and a list of errors.
+
+It accepts 3 parameters:
+* `template {String}` the template file content as a string.
+* `path {String}` path of a file being compiled (optional - used for error messages).
+* `options {Object}` supported options are:
+  * `includeSyntaxTree {Boolean}` if true, the result object will contain the syntax tree generated by the compiler.
+  * `bypassJSvalidation {Boolean}` if true, the validation of the generated JS file (including non-template code) is bypassed - default:false.
+  * `mode {String}` the type of module system the code shold comply with: either "commonJS" or "global" 
+  * `globalRef {String}` the name of the runtime global reference when the "global" mode is used (default: "hsp")
+
+
+The returned object contains:
+* `errors {Array}` the error list - each error having the following structure:
+  * `description {String}` a message describing the error
+  * `line {Number}` the error line number
+  * `column {Number}` the error column number 
+  * `code {String}` a code extract showing where the error occurs (optional)
+* `code {String}` the generated JavaScript code
+* `syntaxTree {JSON}` the syntax tree generated by the parser (optional)
+* `lineMap {Array}` array of the new line indexes; i.e. lineMap[3] returns the new line index for line 4 in the orginal file (lineMap[0] is always 0 as all line count starts at 1 for both input and output values).
+
 
 ## Template statements
 
@@ -790,16 +811,34 @@ var Child = klass({
 
 User method called to properly clean a _destroyed_ instance.
 
-##### Accessing parent class methods
+##### Calling an overridden parent class method
 
-TBD
+In order to call a method `fakeMethod` of a parent class `fakeClass`, when it has been overridden, it is sufficient to call `fakeClass.fakeMethod()`, without using the `prototype` property, as it is done for the `$constructor` method in the following example.
 
+```javascript
+var ClassC = klass({
+  $extends : ClassB,
+  $constructor : function (incr) {
+    ClassB.$constructor.call(this);
+    this.idx += incr;
+  }  
+}); 
+```
 
 #### Model updates
 
 ##### Object update
 
-TBD
+To implement data-binding, Hashspace reprocesses JavaScript to introduce a partial polyfill to Object.observe and detect changes that occur to JavaScript objects. Hashspace actually uses a transpiler to encapsulate assignments with an internal `$set()` method that performs the assignment and notifies the potential observers. 
+
+In the mid-term the $set() utility will become obsolete, once the Object.observe feature is implemented by all web-browsers, and Hashspace will rely on the browser's Object.observe implementation.
+
+The $set function has the following signature:
+
+`$set(object_or_array, propertyName_or_index, value);`
+
+In order to let the transpiler introduce the logic to observe an object, the latter has to be specified in the assignment as its father's property (i.e. `a.b = 3`).
+
 
 ##### Array update
 
@@ -826,11 +865,13 @@ array.splice2(2, 0, ['c', 'd']); // => ['a', 'b', 'c', 'd', 'e', 'f']
 
 ##### hsp.refresh()
 
-TBD
+The refresh method automatically refreshes all templates that may have been impacted by changes in data structures.
+It is automatically triggered by a setTimeout, thus it may be explicitly used in some uncommon cases only (when a refresh has to be forced before performing another operation).
+
 
 ##### hsp.template()
 
-TBD
+This method does not need to be explicitly called because it is internally used to create template functions from the ones generated by the transpiler.
 
 ---
 
@@ -953,65 +994,126 @@ log.addLogger(function(entry) {
 
 #### Create a `new TestContext()`
 
-TBD
+In order to write tests with hashtester, you need to instantiate a `TestContext` object
+```javascript
+var ht = require("hsp/utils/hashtester");
+var testCtxt = ht.newTestContext();
+```
 
 ---
 
 #### Test context usage
 
-TBD
+A test context is a function object that exposes the following properties and methods:
 
-##### Selector accessor `.()`
 
-* ###### `.find()`
+* ##### container: {DOMElement}
+  It contains a DOM element to insert the template in.
 
-  TBD
 
-* ###### `.text()`
+* ##### $set(container, property, value)
 
-  TBD
+  It performs the assignment, notifies the potential observers and forces an hashspace refresh.
 
-* ###### `.value()`
+  Parameters: 
+  * {Object} `container` the object that contains a property to be set
+  * {String} `property` the property to be set
+  * {Object} `value` the value to be assigned to the given property
 
-  TBD
 
-* ###### `.attribute()`
+* ##### $dispose()
 
-  TBD
+  This method is used when the test context has to be disposed, in order to destroy all the logs and objects, managed by the `SelectionWrapper` instance.
 
-* ###### `.hasClass()`
 
-  TBD
+* ##### logs(idx)
 
-* ###### `.item()`
+  This method returns an array (if the parameter is not specified), otherwise it returns the corresponding log message.
 
-  TBD
+  Parameters: 
+  * {integer} `idx` the position of the log message (first index = 0)
 
-* ###### `.click()`
+  Furthermore, the logs object exposes the following method:
+  * ###### `clear()`
+    It resets the log message list.
 
-  TBD
 
-* ###### `.dblclick()`
+#### Selector accessor `.(selector)`
 
-  TBD
+Using the `TestContext` function it is possible to retrive an array of DOM elements, filtered according to the provided selector (as it is done in jQuery by means of the `$` object); it returns a `SelectionWrapper` object. 
 
-* ###### `.type()`
+i.e:
+```javascript
+var HEAD = testCtxt(".panel .head"); 
+```
 
-  TBD
+---
 
+#### `SelectionWrapper` Class
 
-##### logs()
+An instance of `SelectionWrapper` provides the following methods:
 
-* ###### `.clear()`
+* ###### `find(selector)`
 
-  TBD
+  It permits to further refine the selection by applying a new selector.
 
-##### $set()
+  Parameters: 
+  * {String} `selector`: the selector expression (jquery selector syntax)
 
-TBD
 
-##### $dispose()
+* ###### `text(trim)`
+
+  It returns the textual content of the selection (by recursively going through all DOM sub-nodes) and concatenates the different text node content.
+
+  Parameters: 
+  * {Boolean} `trim`: whether the returned text has to be trimmed - true by default
+
+
+* ###### `value()`
+
+  This method returns the value of input or textarea elements.
+
+
+* ###### `attribute(attName)`
+
+  It returns the value of an attribute of the selected node (it only works on single-element selections).
+
+  Parameters: 
+  * {String} `attName` the name of the attribute - e.g. "title"
+
+
+* ###### `hasClass(cssClassName)`
+
+  This method tells if the first element in the selection is assigned a specified CSS class.
+
+  Parameters: 
+  * {String} `cssClassName` the class name to check
+
+
+* ###### `item(idx)`
+
+  It returns the selection corresponding to the nth element in the selection.
+
+  Parameters: 
+  * {integer} `idx` the position of the element (first index = 0)
+
+
+* ###### `click()`
+
+  It simulates a click event on the selected element and triggers an hashspace refresh.
+
+
+* ###### `dblclick()`
+
+  It simulates a double click event on the selected element and triggers an hashspace refresh.
+
+
+* ###### `type(text)`
+
+  It simulates a type event and triggers an hashspace refresh
+
+  Parameters: 
+  * {String} `text` the text to be typed
 
-TBD
 
 [CONTENT_END]