improved docs

liabru · Dec 27, 2015 · 2e6afd4 · 2e6afd4
1 parent 110aea8
commit 2e6afd4
Show file tree

Hide file tree

Showing 28 changed files with 149 additions and 152 deletions.
diff --git a/src/body/Body.js b/src/body/Body.js
@@ -3,8 +3,7 @@
 * A `Matter.Body` is a rigid body that can be simulated by a `Matter.Engine`.
 * Factories for commonly used body configurations (such as rectangles, circles and other polygons) can be found in the module `Matter.Bodies`.
 *
-* See [Demo.js](https://github.com/liabru/matter-js/blob/master/demo/js/Demo.js) 
-* and [DemoMobile.js](https://github.com/liabru/matter-js/blob/master/demo/js/DemoMobile.js) for usage examples.
+* See the included usage [examples](https://github.com/liabru/matter-js/tree/master/examples).
 
 * @class Body
 */

diff --git a/src/body/Composite.js b/src/body/Composite.js
@@ -4,8 +4,7 @@
 * It is important to use the functions in this module to modify composites, rather than directly modifying their properties.
 * Note that the `Matter.World` object is also a type of `Matter.Composite` and as such all composite methods here can also operate on a `Matter.World`.
 *
-* See [Demo.js](https://github.com/liabru/matter-js/blob/master/demo/js/Demo.js) 
-* and [DemoMobile.js](https://github.com/liabru/matter-js/blob/master/demo/js/DemoMobile.js) for usage examples.
+* See the included usage [examples](https://github.com/liabru/matter-js/tree/master/examples).
 *
 * @class Composite
 */
@@ -152,7 +151,7 @@ var Body = require('./Body');
     };
 
     /**
-     * Adds a composite to the given composite
+     * Adds a composite to the given composite.
      * @private
      * @method addComposite
      * @param {composite} compositeA
@@ -167,7 +166,7 @@ var Body = require('./Body');
     };
 
     /**
-     * Removes a composite from the given composite, and optionally searching its children recursively
+     * Removes a composite from the given composite, and optionally searching its children recursively.
      * @private
      * @method removeComposite
      * @param {composite} compositeA
@@ -192,7 +191,7 @@ var Body = require('./Body');
     };
 
     /**
-     * Removes a composite from the given composite
+     * Removes a composite from the given composite.
      * @private
      * @method removeCompositeAt
      * @param {composite} composite
@@ -206,7 +205,7 @@ var Body = require('./Body');
     };
 
     /**
-     * Adds a body to the given composite
+     * Adds a body to the given composite.
      * @private
      * @method addBody
      * @param {composite} composite
@@ -220,7 +219,7 @@ var Body = require('./Body');
     };
 
     /**
-     * Removes a body from the given composite, and optionally searching its children recursively
+     * Removes a body from the given composite, and optionally searching its children recursively.
      * @private
      * @method removeBody
      * @param {composite} composite
@@ -245,7 +244,7 @@ var Body = require('./Body');
     };
 
     /**
-     * Removes a body from the given composite
+     * Removes a body from the given composite.
      * @private
      * @method removeBodyAt
      * @param {composite} composite
@@ -259,7 +258,7 @@ var Body = require('./Body');
     };
 
     /**
-     * Adds a constraint to the given composite
+     * Adds a constraint to the given composite.
      * @private
      * @method addConstraint
      * @param {composite} composite
@@ -273,7 +272,7 @@ var Body = require('./Body');
     };
 
     /**
-     * Removes a constraint from the given composite, and optionally searching its children recursively
+     * Removes a constraint from the given composite, and optionally searching its children recursively.
      * @private
      * @method removeConstraint
      * @param {composite} composite
@@ -297,7 +296,7 @@ var Body = require('./Body');
     };
 
     /**
-     * Removes a body from the given composite
+     * Removes a body from the given composite.
      * @private
      * @method removeConstraintAt
      * @param {composite} composite
@@ -311,8 +310,8 @@ var Body = require('./Body');
     };
 
     /**
-     * Removes all bodies, constraints and composites from the given composite
-     * Optionally clearing its children recursively
+     * Removes all bodies, constraints and composites from the given composite.
+     * Optionally clearing its children recursively.
      * @method clear
      * @param {composite} composite
      * @param {boolean} keepStatic
@@ -339,7 +338,7 @@ var Body = require('./Body');
     };
 
     /**
-     * Returns all bodies in the given composite, including all bodies in its children, recursively
+     * Returns all bodies in the given composite, including all bodies in its children, recursively.
      * @method allBodies
      * @param {composite} composite
      * @return {body[]} All the bodies
@@ -354,7 +353,7 @@ var Body = require('./Body');
     };
 
     /**
-     * Returns all constraints in the given composite, including all constraints in its children, recursively
+     * Returns all constraints in the given composite, including all constraints in its children, recursively.
      * @method allConstraints
      * @param {composite} composite
      * @return {constraint[]} All the constraints
@@ -369,7 +368,7 @@ var Body = require('./Body');
     };
 
     /**
-     * Returns all composites in the given composite, including all composites in its children, recursively
+     * Returns all composites in the given composite, including all composites in its children, recursively.
      * @method allComposites
      * @param {composite} composite
      * @return {composite[]} All the composites
@@ -384,7 +383,7 @@ var Body = require('./Body');
     };
 
     /**
-     * Searches the composite recursively for an object matching the type and id supplied, null if not found
+     * Searches the composite recursively for an object matching the type and id supplied, null if not found.
      * @method get
      * @param {composite} composite
      * @param {number} id
@@ -418,7 +417,7 @@ var Body = require('./Body');
     };
 
     /**
-     * Moves the given object(s) from compositeA to compositeB (equal to a remove followed by an add)
+     * Moves the given object(s) from compositeA to compositeB (equal to a remove followed by an add).
      * @method move
      * @param {compositeA} compositeA
      * @param {object[]} objects
@@ -432,7 +431,7 @@ var Body = require('./Body');
     };
 
     /**
-     * Assigns new ids for all objects in the composite, recursively
+     * Assigns new ids for all objects in the composite, recursively.
      * @method rebase
      * @param {composite} composite
      * @return {composite} Returns composite

diff --git a/src/body/World.js b/src/body/World.js
@@ -5,8 +5,7 @@
 * It is important to use the functions in the `Matter.Composite` module to modify the world composite, rather than directly modifying its properties.
 * There are also a few methods here that alias those in `Matter.Composite` for easier readability.
 *
-* See [Demo.js](https://github.com/liabru/matter-js/blob/master/demo/js/Demo.js) 
-* and [DemoMobile.js](https://github.com/liabru/matter-js/blob/master/demo/js/DemoMobile.js) for usage examples.
+* See the included usage [examples](https://github.com/liabru/matter-js/tree/master/examples).
 *
 * @class World
 * @extends Composite

diff --git a/src/collision/Contact.js b/src/collision/Contact.js
@@ -1,5 +1,5 @@
 /**
-* _Internal Class_, not generally used outside of the engine's internals.
+* The `Matter.Contact` module contains methods for creating and manipulating collision contacts.
 *
 * @class Contact
 */
@@ -11,7 +11,7 @@ module.exports = Contact;
 (function() {
 
     /**
-     * Description
+     * Creates a new contact.
      * @method create
      * @param {vertex} vertex
      * @return {contact} A new contact
@@ -26,7 +26,7 @@ module.exports = Contact;
     };
 
     /**
-     * Description
+     * Generates a contact id.
      * @method id
      * @param {vertex} vertex
      * @return {string} Unique contactID

diff --git a/src/collision/Detector.js b/src/collision/Detector.js
@@ -1,5 +1,5 @@
 /**
-* _Internal Class_, not generally used outside of the engine's internals.
+* The `Matter.Detector` module contains methods for detecting collisions given a set of pairs.
 *
 * @class Detector
 */
@@ -17,7 +17,7 @@ var Bounds = require('../geometry/Bounds');
 (function() {
 
     /**
-     * Description
+     * Finds all collisions given a list of pairs.
      * @method collisions
      * @param {pair[]} broadphasePairs
      * @param {engine} engine

diff --git a/src/collision/Grid.js b/src/collision/Grid.js
@@ -1,6 +1,5 @@
 /**
-* See [Demo.js](https://github.com/liabru/matter-js/blob/master/demo/js/Demo.js) 
-* and [DemoMobile.js](https://github.com/liabru/matter-js/blob/master/demo/js/DemoMobile.js) for usage examples.
+* The `Matter.Grid` module contains methods for creating and manipulating collision broadphase grid structures.
 *
 * @class Grid
 */
@@ -16,7 +15,7 @@ var Common = require('../core/Common');
 (function() {
 
     /**
-     * Description
+     * Creates a new grid.
      * @method create
      * @param {} options
      * @return {grid} A new grid
@@ -36,7 +35,7 @@ var Common = require('../core/Common');
     };
 
     /**
-     * Description
+     * Updates the grid.
      * @method update
      * @param {grid} grid
      * @param {body[]} bodies
@@ -125,7 +124,7 @@ var Common = require('../core/Common');
     };
 
     /**
-     * Description
+     * Clears the grid.
      * @method clear
      * @param {grid} grid
      */
@@ -136,12 +135,12 @@ var Common = require('../core/Common');
     };
 
     /**
-     * Description
+     * Finds the union of two regions.
      * @method _regionUnion
      * @private
      * @param {} regionA
      * @param {} regionB
-     * @return CallExpression
+     * @return {} region
      */
     var _regionUnion = function(regionA, regionB) {
         var startCol = Math.min(regionA.startCol, regionB.startCol),
@@ -153,12 +152,12 @@ var Common = require('../core/Common');
     };
 
     /**
-     * Description
+     * Gets the region a given body falls in for a given grid.
      * @method _getRegion
      * @private
      * @param {} grid
      * @param {} body
-     * @return CallExpression
+     * @return {} region
      */
     var _getRegion = function(grid, body) {
         var bounds = body.bounds,
@@ -171,14 +170,14 @@ var Common = require('../core/Common');
     };
 
     /**
-     * Description
+     * Creates a region.
      * @method _createRegion
      * @private
      * @param {} startCol
      * @param {} endCol
      * @param {} startRow
      * @param {} endRow
-     * @return ObjectExpression
+     * @return {} region
      */
     var _createRegion = function(startCol, endCol, startRow, endRow) {
         return { 
@@ -191,32 +190,32 @@ var Common = require('../core/Common');
     };
 
     /**
-     * Description
+     * Gets the bucket id at the given position.
      * @method _getBucketId
      * @private
      * @param {} column
      * @param {} row
-     * @return BinaryExpression
+     * @return {string} bucket id
      */
     var _getBucketId = function(column, row) {
         return column + ',' + row;
     };
 
     /**
-     * Description
+     * Creates a bucket.
      * @method _createBucket
      * @private
      * @param {} buckets
      * @param {} bucketId
-     * @return bucket
+     * @return {} bucket
      */
     var _createBucket = function(buckets, bucketId) {
         var bucket = buckets[bucketId] = [];
         return bucket;
     };
 
     /**
-     * Description
+     * Adds a body to a bucket.
      * @method _bucketAddBody
      * @private
      * @param {} grid
@@ -248,7 +247,7 @@ var Common = require('../core/Common');
     };
 
     /**
-     * Description
+     * Removes a body from a bucket.
      * @method _bucketRemoveBody
      * @private
      * @param {} grid
@@ -273,11 +272,11 @@ var Common = require('../core/Common');
     };
 
     /**
-     * Description
+     * Generates a list of the active pairs in the grid.
      * @method _createActivePairsList
      * @private
      * @param {} grid
-     * @return pairs
+     * @return [] pairs
      */
     var _createActivePairsList = function(grid) {
         var pairKeys,
@@ -303,4 +302,4 @@ var Common = require('../core/Common');
         return pairs;
     };
 
-})();
+})();