Issue 258 - [Typed objects] Implement a garbage collection mechanism

lib/typedObjects.js

Index: lib/typedObjects.js
===================================================================
--- a/lib/typedObjects.js
+++ b/lib/typedObjects.js
@@ -40,30 +40,47 @@
  * name can either be associted with a type (property) or function (method).
  * Numeric value types from the ECMAScript Harmony proposal are predefined as
  * well as "boolean" which is an alias for uint8. In addition to that, already
  * defined object types can be used.
  *
  * The optional second parameter sets type metadata:
  *
  *    constructor: function that will be called whenever an object of the type
- *        is created.
+ *        is created. Parameters supplied during object creation will be passed
+ *        to the constructor.
+ *    destructor: function that will be called when an object of the type is
+ *        freed.
  *    bufferSize: number of objects that should be placed into a single typed
  *        buffer (by default 128).
  *
- * Creating an object instance
- * ---------------------------
+ * Creating and releasing an object instance
+ * -----------------------------------------
  *
  *    var point = Point2D(5, 10);
  *    point.rotate(10);
- *    Console.log(point.x + ", " + point.y);
+ *    console.log(point.x + ", " + point.y);
  *
  * The parameters 5 and 10 will be passed to the constructor function defined
  * for this type.
  *
+ * Once the object instance is no longer needed it should be released:
+ *
+ *    point.release();
+ *
+ * This will not necessarily free the object but merely decrease its reference
+ * count. The object will only be freed when its reference count reaches zero.
+ *
+ * If you need to hold on to an object that you didn't create (e.g. a function
+ * parameter) you have to call object.retain() to increase its reference count.
+ * Once the object is no longer needed you should call object.release().
+ * However, it is preferable to use references from other typed objects to hold
+ * on to an object - the necessary reference count increases and decreases will
+ * be performed automatically then.
+ *
  * Type inheritance
  * ----------------
  *
  *    var Point3D = Point2D.extend({
  *      z: uint32
  *    }, {
  *      constructor: function(super_, x, y, z)
  *      {