docs...

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>

README.md

@@ -18,7 +18,7 @@ several advantages:
 
 Disadvantages compared to the `class` syntax:  
 - no _syntactic sugar_
-- a slightly more complicated `super` call method
+- slightly more complicated calling of _super_ or `parent` methods
 
 
 ## Usage
@@ -95,19 +95,11 @@ var Item = object.Constructor('Item', {
 
 
 ### Callable instances
+
 ```javascript
 // callable instance constructor...
 var Action = object.Constructor('Action',
-    // Define a constructor as a function...
+    // constructor as a function...
-    //
-    // The first argument is allways the external call context, like
-    // normal this, but here we have two contexts:
-    //  - internal (this)       -- the instance (this)
-    //  - external (context)    -- call context
-    //
-    // NOTE: if the prototype is explicitly defined as a function then
-    //      it is the user's responsibility to call .__call__(..) method
-    //      (see below)
     function(context, ...args){
         // return the instance...
         return this
@@ -119,17 +111,12 @@ action()
 
 
 // a different way to do the above...
+//
+// This is the same as the above but a bit more convenient as we do 
+// not need to use Object.assign(..) or object.mixinFlat(..) to define
+// attributes and props.
+
 var Action2 = object.Constructor('Action2', {
-    // This is the same as the above but a bit more convenient as we do 
-    // not need to use Object.assign(..) or object.mixinFlat(..) to define
-    // attributes and props.
-    //
-    // Contexts:
-    //  - internal (this)       -- the instance
-    //  - external (context)    -- call context
-    //
-    // NOTE: this is not called if a user defines the prototype as a function
-    //      (see above)
     __call__: function(context, ...args){
         return this
     },
@@ -137,19 +124,23 @@ var Action2 = object.Constructor('Action2', {
 
 ```
 
+In the above cases both the base function and the `.__call__(..)` method
+receive a `context` argument in addition to `this` context, those represent 
+the two contexts relevant to the callable instance:
+- Internal context (`this`)
+  This always references the instance being called
+- External context (`context`)
+  This is the object the instance is called from (`window` or `global` by 
+  default), i.e. _the thing before the dot_
+
+If the prototype is explicitly defined as a function then it is the 
+user's responsibility to call .__call__(..) method.
+
+
 ### Low level constructor
+
 ```javascript
 var LowLevel = object.Constructor('LowLevel', {
-    // Low level instance constructor...
-    //
-    // Contexts:
-    //  - internal (this)       -- .prototype
-    //  - external (context)    -- call context
-    //
-    // NOTE: if this is defined the return value is used as the instance
-    // NOTE: this has priority over the callable protocols above, thus
-    //      the user must take care of both the prototype as function and
-    //      prototype.__call__(..)...
     __new__: function(context, ...args){
         return {}
     },
@@ -157,30 +148,61 @@ var LowLevel = object.Constructor('LowLevel', {
 
 ```
 
+Like function constructor and `.__call__(..)` this also has two contexts,
+but the internal context is different -- as it is the job of `.__new__(..)`
+to create an instance at time of call the instance does not exist and `this`
+references the `.prototype` object.
+The external context is the same as above.
+
+Contexts:
+- Internal context (`this`)
+  References the `.prototype` of the constructor.
+- External context (`context`)
+  This is the object the instance is called from (`window` or `global` by 
+  default), i.e. _the thing before the dot_, the same as for function 
+  constructor and `.__call__(..)`.
+ 
+
+The value `.__new__(..)`returns is used as the instance and gets linked 
+in the prototype chain.
+
+This has priority over the callable protocols above, thus the user must
+take care of both the _prototype as function_ and `prototype.__call__(..)` 
+handling.
+
+
 ## Components
 
+Get sources for attribute
 ```
 sources(<object>, <name>)
 sources(<object>, <name>, <callback>)
     -> <list>
 ```
 
+Get parent method
 ```
 parent(<method>, <this>)
 parent(<method>, <name>, <this>)
     -> <parent-method>
 ```
 
+Mixin objects into a prototype chain
 ```
 mixin(<root>, <object>, ...)
     -> <object>
 ```
 
+Mixin contents of objects into one
 ```
 mixinFlat(<root>, <object>, ...)
     -> <object>
 ```
+This is like `Object.assign(..)` but copies property objects rather than
+property values.
 
+
+Define an object constructor
 ```
 Constructor(<name>, <prototype>)
 Constructor(<name>, <class-prototype>, <prototype>)