Updating ReadMe to reflect new functionality.

README.md

@@ -1,55 +1,82 @@
 # Recycle #
 
-This project enables simple object pooling to speed up object creation and avoid garbage collection. To use, simply include `recycle.js` in your project. Once included, it adds a `recycle` object to `window`. This object exposes a single method `add` to add recycling to an object definition. For example:
+This project enables simple object pooling to speed up object creation and reduce garbage collection. To use, simply include `recycle.js` in your project.
 
-    var Box = function (size) {
-        this.size = size;
-    };
+    include recycle from 'recycle.js';
 
-    window.recycle.add(Box);
+The `recycle` object exposes an `add` method to add recycling to an object definition. For example:
+
+    const Box = function (size) {
+            this.size = size;
+        },
+        boxCache = recycle.add(Box, 'Box');
 
 Now `Box` objects will be recyclable. For more control, you can specify additional parameters as follows:
 
-1. class - Object definition to add recycling to.
-2. debug - Whether to log recycling issues to the console. For example, if an object is recycled twice, there may be issues. This is slower, but better to use during development.
-3. name - The name of the object type. This is useful when referencing the list of key/value pairs at `window.recycle.cache` that lists all unused cached objects.
-4. recycle - An alternative recycling function to use. This is useful if any tear-down is needed, but should always include `[ObjectName].recycle(this)` to add the object to the cache for reuse.
+1. **ClassObject** (Object, required) - Object definition to add recycling to. (`Box` above.)
+2. **name** (String, required) - The name of the object type. This maintains a key reference in `recycle.cache` containing all unused, cached objects.
+3. **setUp** (Function, optional) - An initialization method that should be called when a new instance is created if there is any object set-up involved. For factory functions, this could just be the constructor itself.
+4. **tearDown** (Function, optional) - A tear-down method that should be called when an instance is recycled. This is a good place to `null` or `0` out properties before storing in cache for re-use later.
+5. **mixinMethods** (Boolean, optional) - By default, this is `false`, but set to `true` to add static `setUp` and `recycle` methods to the recyclable object, and a `recycle` method to the recyclable object's prototype. This makes set-up and recycling more convenient, but be a good neighbor and do not set this to `true` for objects you don't control (for example, `Array`) as it *may* conflict with pre-existing methods.
+6. **debug** (Boolean, optional) - Sets whether to log recycling issues to the console. For example, if an object is recycled twice, there may be issues. This is slower, but highly recommended to be used during development.
 
-For the above example, we might use 
+The `add` method returns a cache object that exposes a `setUp` method for getting a new object and a `recycle` method for returning an object to this cache. This same cache object is available at `recycle.cache[name]`.
 
-    var Box = function (size) {
-        this.size = size;
-    };
+For the above example, we might do:
 
-    window.recycle.add(Box, true, 'Box', function () {
-        this.size = '';
-        Box.recycle(this);
-    });
+    const Box = function (size) {
+            this.size = size;
+        },
+        boxCache = recycle.add(Box, 'Box', Box, function () {
+            this.size = '';
+        }, true, true);
 
-Recyclable constructors are given two methods to manage recycling: `setUp` and `recycle`. Additionally, a `recycle` method is added to the object's prototype for easy reference and can be overridden as shown above. So, for example, instead of using:
+When `mixinMethods` is set to `true`, recyclable objects are given two methods to manage recycling: `setUp` and `recycle`. Additionally, a `recycle` method is added to the object's prototype for easy reference.
 
-    var box = new Box('big');
+So, for example, instead of using:
 
-To use a recycled `Box` or create a new instance if none are available, use the following:
+    const box = new Box('big');
 
-    var box = Box.setUp('big');
+To use a recycled `Box` or create a new instance if none are available, use any of the following:
 
-And then once it's no longer needed, it can be returned to the cache by:
+    // Get a new Box from `recycle`
+    const box = recycle.cache['Box'].setUp('small');
+
+    // Get a new Box from local cache reference
+    const box = boxCache.setUp('small');
 
-    box.recycle();
+    // If `mixinMethods` is `true`, use the class object itself
+    const box = Box.setUp('small');
+
+And then once it's no longer needed, it can be returned to the cache using any of the following:
+
+    // Recycle from the `recycle` object
+    recycle.cache['Box'].recycle(box);
 
-Or:
+    // Recycle from local cache reference
+    boxCache.recycle(box);
 
+    // If `mixinMethods` is `true`, use either of the following
+    box.recycle();
+    // or
     Box.recycle(box);
 
-If Array is added to the recycling system, it provides an additional feature. They can recycle multiple dimensions using a single call for convenience. So, for example, a two-dimensional array set up like:
+Finally, if you are storing a reference to a recycled object, as a property for example, be sure to set the property to `null` to prevent accidentally using it later. For example:
+
+    // Getting a box to use
+    this.box = Box.setUp('big');
+
+    // No longer need the box
+    this.box.recycle();
+    this.box = null;
 
-    window.recycle.add(Array);
+If Array is added to the recycling system (without a custom tear-down function), it accepts a parameter to recycle multiple dimensions. So, for example, a two-dimensional array set up like:
 
-    var arr = Array.setUp(Array.setUp(), Array.setUp(), Array.setUp());
+    const arrayCache = recycle.add(Array, 'Array'),
+        arr = arrayCache.setUp(arrayCache.setUp(), arrayCache.setUp());
 
-Can be recycled by passing its dimensions into the `recycle` method:
+Can be fully recycled by passing its dimensions into the `recycle` method:
 
     arr.recycle(2)
 
-Objects currently in use are not referenceable from the recycling system, but all unused cached objects are accessible from `window.recycle.cache`.
+Objects currently in use are not referenceable from the recycling system, but all unused cached objects are accessible from `recycle.cache`.