added docs for Matter.Plugin with tweaks

Author: liabru

examples/plugin.js

@@ -41,7 +41,7 @@
         }
     };
 
-    Matter.Plugin.exports(MatterPlugin);
+    Matter.Plugin.register(MatterPlugin);
 
     window.MatterPlugin = MatterPlugin;
 

examples/plugin2.js

@@ -29,7 +29,7 @@
         }
     };
 
-    Matter.Plugin.exports(MatterPlugin2);
+    Matter.Plugin.register(MatterPlugin2);
 
     window.MatterPlugin2 = MatterPlugin2;
 

src/core/Common.js

@@ -303,6 +303,7 @@ module.exports = Common;
     /**
      * The console logging level to use, where each level includes all levels above and excludes the levels below.
      * The default level is 'debug' which shows all console messages.  
+     *
      * Possible level values are:
      * - 0 = None
      * - 1 = Debug
@@ -317,7 +318,7 @@ module.exports = Common;
 
     /**
      * Shows a `console.log` message only if the current `Common.logLevel` allows it.
-     * The message will be prefixed with 'Matter.js' to make it easily identifiable.
+     * The message will be prefixed with 'matter-js' to make it easily identifiable.
      * @method log
      * @param ...objs {} The objects to log.
      */
@@ -329,7 +330,7 @@ module.exports = Common;
 
     /**
      * Shows a `console.info` message only if the current `Common.logLevel` allows it.
-     * The message will be prefixed with 'Matter.js' to make it easily identifiable.
+     * The message will be prefixed with 'matter-js' to make it easily identifiable.
      * @method info
      * @param ...objs {} The objects to log.
      */
@@ -341,7 +342,7 @@ module.exports = Common;
 
     /**
      * Shows a `console.warn` message only if the current `Common.logLevel` allows it.
-     * The message will be prefixed with 'Matter.js' to make it easily identifiable.
+     * The message will be prefixed with 'matter-js' to make it easily identifiable.
      * @method warn
      * @param ...objs {} The objects to log.
      */
@@ -451,14 +452,27 @@ module.exports = Common;
      * The value of `this` refers to the last value returned in the chain that was not `undefined`.
      * Therefore if a passed function does not return a value, the previously returned value is maintained.
      * After all passed functions have been called the new function returns the last returned value (if any).
+     * If any of the passed functions are a chain, then the chain will be flattened.
      * @method chain
      * @param ...funcs {function} The functions to chain.
      * @return {function} A new function that calls the passed functions in order.
      */
     Common.chain = function() {
-        var funcs = Array.prototype.slice.call(arguments);
+        var args = Array.prototype.slice.call(arguments),
+            funcs = [];
 
-        return function() {
+        for (var i = 0; i < args.length; i += 1) {
+            var func = args[i];
+
+            if (func._chained) {
+                // flatten already chained functions
+                funcs.push.apply(funcs, func._chained);
+            } else {
+                funcs.push(func);
+            }
+        }
+
+        var chain = function() {
             var lastResult;
 
             for (var i = 0; i < funcs.length; i += 1) {
@@ -471,6 +485,10 @@ module.exports = Common;
 
             return lastResult;
         };
+
+        chain._chained = funcs;
+
+        return chain;
     };
 
 })();

src/core/Matter.js

@@ -1,5 +1,5 @@
 /**
-* The `Matter` module is the top level namespace and includes functions for extending other modules.
+* The `Matter` module is the top level namespace. It also includes a function for installing plugins on top of the library.
 *
 * @class Matter
 */
@@ -14,47 +14,46 @@ var Plugin = require('./Plugin');
 
     /**
      * The library name.
-     * @property Matter.name
+     * @property name
+     * @readOnly
      * @type {String}
      */
     Matter.name = 'matter-js';
 
     /**
      * The library version.
-     * @property Matter.version
+     * @property version
+     * @readOnly
      * @type {String}
      */
     Matter.version = 'master';
 
     /**
-     * The plugins that have been _installed_ through `Matter.Plugin.install`. Read only.
-     * @property Matter.used
-     * @readOnly
+     * A list of plugin dependencies to be installed. These are normally set and installed through `Matter.use`.
+     * Alternatively you may set `Matter.uses` manually and install them by calling `Plugin.use(Matter)`.
+     * @property uses
      * @type {Array}
      */
-    Matter.used = [];
+    Matter.uses = [];
 
     /**
-     * A list of plugin dependencies to be installed. These are normally set and installed through `Matter.use`.
-     * Alternatively set them and install manually through `Plugin.installDependencies`.
-     * @property Matter.used
+     * The plugins that have been installed through `Matter.Plugin.install`. Read only.
+     * @property used
      * @readOnly
      * @type {Array}
      */
-    Matter.uses = [];
+    Matter.used = [];
 
     /**
-     * Installs plugins on the `Matter` namespace.
-     * Populates `Matter.used` with an array of the plugins in the order they were applied after dependencies were resolved.
-     * See `Common.use` in `Matter.Common` for more information.
-     * TODO: add link to wiki
+     * Installs the given plugins on the `Matter` namespace.
+     * This is a short-hand for `Plugin.use`, see it for more information.
+     * Call this function once at the start of your code, with all of the plugins you wish to install as arguments.
+     * Avoid calling this function multiple times unless you intend to manually control installation order.
      * @method use
-     * @param ...plugins {Function} The plugins to install on `base`.
+     * @param ...plugin {Function} The plugin(s) to install on `base` (multi-argument).
      */
     Matter.use = function() {
-        Matter.uses = Array.prototype.slice.call(arguments);
-
-        Plugin.installDependencies(Matter);
+        Plugin.use(Matter, Array.prototype.slice.call(arguments));
     };
 
 })();