improved docs

src/body/Body.js

@@ -1,7 +1,11 @@
 /**
+* The `Matter.Body` module contains methods for creating and manipulating body models.
+* 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.
-*
+
 * @class Body
 */
 
@@ -12,7 +16,9 @@ var Body = {};
     var _nextGroupId = 1;
 
     /**
-     * Description to be written.
+     * Creates a new rigid body model. The options parameter is an object that specifies any properties you wish to override the defaults.
+     * All properties have default values, and many are pre-calculated automatically based on other properties.
+     * See the properites section below for detailed information on what you can pass via the `options` object.
      * @method create
      * @param {} options
      * @return {body} body
@@ -62,7 +68,7 @@ var Body = {};
     };
 
     /**
-     * Description
+     * Returns the next unique groupID number.
      * @method nextGroupId
      * @return {Number} Unique groupID
      */
@@ -71,7 +77,7 @@ var Body = {};
     };
 
     /**
-     * Initialises body properties
+     * Initialises body properties.
      * @method _initProperties
      * @private
      * @param {body} body
@@ -104,7 +110,7 @@ var Body = {};
     };
 
     /**
-     * Sets the body as static, including isStatic flag and setting mass and inertia to Infinity
+     * Sets the body as static, including isStatic flag and setting mass and inertia to Infinity.
      * @method setStatic
      * @param {bool} isStatic
      */
@@ -129,7 +135,7 @@ var Body = {};
     };
 
     /**
-     * Description
+     * Zeroes the `body.force` and `body.torque` force buffers.
      * @method resetForcesAll
      * @param {body[]} bodies
      */
@@ -145,7 +151,7 @@ var Body = {};
     };
 
     /**
-     * Description
+     * Applys a mass dependant force to all given bodies.
      * @method applyGravityAll
      * @param {body[]} bodies
      * @param {vector} gravity
@@ -164,12 +170,14 @@ var Body = {};
     };
 
     /**
-     * Description
+     * Applys `Body.update` to all given `bodies`.
      * @method updateAll
      * @param {body[]} bodies
      * @param {number} deltaTime 
+     * The amount of time elapsed between updates
      * @param {number} timeScale
      * @param {number} correction 
+     * The Verlet correction factor (deltaTime / lastDeltaTime)
      * @param {bounds} worldBounds
      */
     Body.updateAll = function(bodies, deltaTime, timeScale, correction, worldBounds) {
@@ -190,7 +198,7 @@ var Body = {};
     };
 
     /**
-     * Description
+     * Performs a simulation step for the given `body`, including updating position and angle using Verlet integration.
      * @method update
      * @param {body} body
      * @param {number} deltaTime
@@ -233,7 +241,7 @@ var Body = {};
     };
 
     /**
-     * Description
+     * Applies a force to a body from a given world-space position, including resulting torque.
      * @method applyForce
      * @param {body} body
      * @param {vector} position
@@ -247,7 +255,7 @@ var Body = {};
     };
 
     /**
-     * Description
+     * Moves a body by a given vector relative to its current position, without imparting any velocity.
      * @method translate
      * @param {body} body
      * @param {vector} translation
@@ -262,7 +270,7 @@ var Body = {};
     };
 
     /**
-     * Description
+     * Rotates a body by a given angle relative to its current angle, without imparting any angular velocity.
      * @method rotate
      * @param {body} body
      * @param {number} angle
@@ -276,12 +284,12 @@ var Body = {};
     };
 
     /**
-     * Scales the body, including updating physical properties (mass, area, axes, inertia), from a point (default is centre)
+     * Scales the body, including updating physical properties (mass, area, axes, inertia), from a world-space point (default is body centre).
      * @method translate
      * @param {body} body
      * @param {number} scaleX
      * @param {number} scaleY
-     * @param {vector} point
+     * @param {vector} [point]
      */
     Body.scale = function(body, scaleX, scaleY, point) {
         // scale vertices
@@ -303,4 +311,365 @@ var Body = {};
         Bounds.update(body.bounds, body.vertices, body.velocity);
     };
 
+    /*
+    *
+    *  Properties Documentation
+    *
+    */
+
+    /**
+     * An integer `Number` uniquely identifying number generated in `Body.create` by `Common.nextId`.
+     *
+     * @property id
+     * @type number
+     */
+
+    /**
+     * A `String` denoting the type of object.
+     *
+     * @property type
+     * @type string
+     * @default "body"
+     */
+
+    /**
+     * An arbitrary `String` name to help the user identify and manage bodies.
+     *
+     * @property label
+     * @type string
+     * @default "Body"
+     */
+
+    /**
+     * A `Number` specifying the angle of the body, in radians.
+     *
+     * @property angle
+     * @type number
+     * @default 0
+     */
+
+    /**
+     * An array of `Vector` objects that specify the convex hull of the rigid body.
+     * These should be provided about the origin `(0, 0)`. E.g.
+     *
+     *     [{ x: 0, y: 0 }, { x: 25, y: 50 }, { x: 50, y: 0 }]
+     *
+     * When passed via `Body.create`, the verticies are translated relative to `body.position` (i.e. world-space, and constantly updated by `Body.update` during simulation).
+     * The `Vector` objects are also augmented with additional properties required for efficient collision detection. 
+     *
+     * Other properties such as `inertia` and `bounds` are automatically calculated from the passed vertices (unless provided via `options`).
+     * Concave hulls are not currently supported. The module `Matter.Vertices` contains useful methods for working with vertices.
+     *
+     * @property vertices
+     * @type vector[]
+     */
+
+    /**
+     * A `Vector` that specifies the current world-space position of the body.
+     *
+     * @property position
+     * @type vector
+     * @default { x: 0, y: 0 }
+     */
+
+    /**
+     * A `Vector` that specifies the force to apply in the current step. It is zeroed after every `Body.update`. See also `Body.applyForce`.
+     *
+     * @property force
+     * @type vector
+     * @default { x: 0, y: 0 }
+     */
+
+    /**
+     * A `Number` that specifies the torque (turning force) to apply in the current step. It is zeroed after every `Body.update`.
+     *
+     * @property torque
+     * @type number
+     * @default 0
+     */
+
+    /**
+     * A `Number` that _measures_ the current speed of the body after the last `Body.update`. It is read-only and always positive (it's the magnitude of `body.velocity`).
+     *
+     * @readOnly
+     * @property speed
+     * @type number
+     * @default 0
+     */
+
+    /**
+     * A `Number` that _measures_ the current angular speed of the body after the last `Body.update`. It is read-only and always positive (it's the magnitude of `body.angularVelocity`).
+     *
+     * @readOnly
+     * @property angularSpeed
+     * @type number
+     * @default 0
+     */
+
+    /**
+     * A `Vector` that _measures_ the current velocity of the body after the last `Body.update`. It is read-only. 
+     * If you need to modify a body's velocity directly, you should either apply a force or simply change the body's `position` (as the engine uses position-Verlet integration).
+     *
+     * @readOnly
+     * @property velocity
+     * @type vector
+     * @default { x: 0, y: 0 }
+     */
+
+    /**
+     * A `Number` that _measures_ the current angular velocity of the body after the last `Body.update`. It is read-only. 
+     * If you need to modify a body's angular velocity directly, you should apply a torque or simply change the body's `angle` (as the engine uses position-Verlet integration).
+     *
+     * @readOnly
+     * @property angularVelocity
+     * @type number
+     * @default 0
+     */
+
+    /**
+     * A flag that indicates whether a body is considered static. A static body can never change position or angle and is completely fixed.
+     * If you need to set a body as static after its creation, you should use `Body.setStatic` as this requires more than just setting this flag.
+     *
+     * @property isStatic
+     * @type boolean
+     * @default false
+     */
+
+    /**
+     * A flag that indicates whether the body is considered sleeping. A sleeping body acts similar to a static body, except it is only temporary and can be awoken.
+     * If you need to set a body as sleeping, you should use `Sleeping.set` as this requires more than just setting this flag.
+     *
+     * @property isSleeping
+     * @type boolean
+     * @default false
+     */
+
+    /**
+     * A `Number` that _measures_ the amount of movement a body currently has (a combination of `speed` and `angularSpeed`). It is read-only and always positive.
+     * It is used and updated by the `Matter.Sleeping` module during simulation to decide if a body has come to rest.
+     *
+     * @readOnly
+     * @property motion
+     * @type number
+     * @default 0
+     */
+
+    /**
+     * A `Number` that defines the number of updates in which this body must have near-zero velocity before it is set as sleeping by the `Matter.Sleeping` module (if sleeping is enabled by the engine).
+     *
+     * @property sleepThreshold
+     * @type number
+     * @default 60
+     */
+
+    /**
+     * A `Number` that defines the density of the body, that is its mass per unit area.
+     * If you pass the density via `Body.create` the `mass` property is automatically calculated for you based on the size (area) of the object.
+     * This is generally preferable to simply setting mass and allows for more intuitive definition of materials (e.g. rock has a higher density than wood).
+     *
+     * @property density
+     * @type number
+     * @default 0.001
+     */
+
+    /**
+     * A `Number` that defines the mass of the body, although it may be more appropriate to specify the `density` property instead.
+     * If you modify this value, you must also modify the `body.inverseMass` property (`1 / mass`).
+     *
+     * @property mass
+     * @type number
+     */
+
+    /**
+     * A `Number` that defines the inverse mass of the body (`1 / mass`).
+     * If you modify this value, you must also modify the `body.mass` property.
+     *
+     * @property inverseMass
+     * @type number
+     */
+
+    /**
+     * A `Number` that defines the moment of inertia (i.e. second moment of area) of the body.
+     * It is automatically calculated from the given convex hull (`vertices` array) and density in `Body.create`.
+     * If you modify this value, you must also modify the `body.inverseInertia` property (`1 / inertia`).
+     *
+     * @property inertia
+     * @type number
+     */
+
+    /**
+     * A `Number` that defines the inverse moment of inertia of the body (`1 / inertia`).
+     * If you modify this value, you must also modify the `body.inertia` property.
+     *
+     * @property inverseInertia
+     * @type number
+     */
+
+    /**
+     * A `Number` that defines the restitution (elasticity) of the body. The value is always positive and is in the range `(0, 1)`.
+     * A value of `0` means collisions may be perfectly inelastic and no bouncing may occur. 
+     * A value of `0.8` means the body may bounce back with approximately 80% of its kinetic energy.
+     * Note that collision response is based on _pairs_ of bodies, and that `restitution` values are _combined_ with the following formula:
+     *
+     *     Math.max(bodyA.restitution, bodyB.restitution)
+     *
+     * @property restitution
+     * @type number
+     * @default 0
+     */
+
+    /**
+     * A `Number` that defines the friction of the body. The value is always positive and is in the range `(0, 1)`.
+     * A value of `0` means that the body may slide indefinitely.
+     * A value of `1` means the body may come to a stop almost instantly after a force is applied.
+     *
+     * The effects of the value may be non-linear. 
+     * High values may be unstable depending on the body.
+     * The engine uses a Coulomb friction model including static and kinetic friction.
+     * Note that collision response is based on _pairs_ of bodies, and that `friction` values are _combined_ with the following formula:
+     *
+     *     Math.min(bodyA.friction, bodyB.friction)
+     *
+     * @property friction
+     * @type number
+     * @default 0.1
+     */
+
+    /**
+     * A `Number` that defines the air friction of the body (air resistance). 
+     * A value of `0` means the body will never slow as it moves through space.
+     * The higher the value, the faster a body slows when moving through space.
+     * The effects of the value are non-linear. 
+     *
+     * @property frictionAir
+     * @type number
+     * @default 0.01
+     */
+
+    /**
+     * An integer `Number` that specifies the collision group the body belongs to. 
+     * Bodies with the same `groupId` are considered _as-one_ body and therefore do not interact.
+     * This allows for creation of segmented bodies that can self-intersect, such as a rope.
+     * The default value 0 means the body does not belong to a group, and can interact with all other bodies.
+     *
+     * @property groupId
+     * @type number
+     * @default 0
+     */
+
+    /**
+     * A `Number` that specifies a tollerance on how far a body is allowed to 'sink' or rotate into other bodies.
+     * Avoid changing this value unless you understand the purpose of `slop` in physics engines.
+     * The default should generally suffice, although very large bodies may require larger values for stable stacking.
+     *
+     * @property slop
+     * @type number
+     * @default 0.05
+     */
+
+    /**
+     * A `Number` that allows per-body time scaling, e.g. a force-field where bodies inside are in slow-motion, while others are at full speed.
+     *
+     * @property timeScale
+     * @type number
+     * @default 1
+     */
+
+    /**
+     * An `Object` that defines the rendering properties to be consumed by the module `Matter.Render`.
+     *
+     * @property render
+     * @type object
+     */
+
+    /**
+     * A flag that indicates if the body should be rendered.
+     *
+     * @property render.visible
+     * @type boolean
+     * @default true
+     */
+
+    /**
+     * An `Object` that defines the sprite properties to use when rendering, if any.
+     *
+     * @property render.sprite
+     * @type object
+     */
+
+    /**
+     * An `String` that defines the path to the image to use as the sprite texture, if any.
+     *
+     * @property render.sprite.texture
+     * @type string
+     */
+     
+    /**
+     * A `Number` that defines the scaling in the x-axis for the sprite, if any.
+     *
+     * @property render.sprite.xScale
+     * @type number
+     * @default 1
+     */
+
+    /**
+     * A `Number` that defines the scaling in the y-axis for the sprite, if any.
+     *
+     * @property render.sprite.yScale
+     * @type number
+     * @default 1
+     */
+
+    /**
+     * A `Number` that defines the line width to use when rendering the body outline (if a sprite is not defined).
+     * A value of `0` means no outline will be rendered.
+     *
+     * @property render.lineWidth
+     * @type number
+     * @default 1.5
+     */
+
+    /**
+     * A `String` that defines the fill style to use when rendering the body (if a sprite is not defined).
+     * It is the same as when using a canvas, so it accepts CSS style property values.
+     *
+     * @property render.fillStyle
+     * @type string
+     * @default a random colour
+     */
+
+    /**
+     * A `String` that defines the stroke style to use when rendering the body outline (if a sprite is not defined).
+     * It is the same as when using a canvas, so it accepts CSS style property values.
+     *
+     * @property render.strokeStyle
+     * @type string
+     * @default a random colour
+     */
+
+    /**
+     * An array of unique axis vectors (edge normals) used for collision detection.
+     * These are automatically calculated from the given convex hull (`vertices` array) in `Body.create`.
+     * They are constantly updated by `Body.update` during the simulation.
+     *
+     * @property axes
+     * @type vector[]
+     */
+     
+    /**
+     * A `Number` that _measures_ the area of the body's convex hull, calculated at creation by `Body.create`.
+     *
+     * @property area
+     * @type string
+     * @default 
+     */
+
+    /**
+     * A `Bounds` object that defines the AABB region for the body.
+     * It is automatically calculated from the given convex hull (`vertices` array) in `Body.create` and constantly updated by `Body.update` during simulation.
+     *
+     * @property bounds
+     * @type bounds
+     */
+
 })();

src/body/Composite.js

@@ -1,4 +1,9 @@
 /**
+* The `Matter.Composite` module contains methods for creating and manipulating composite bodies.
+* A composite body is a collection of `Matter.Body`, `Matter.Constraint` and other `Matter.Composite`, therefore composites form a tree structure.
+* 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.
 *
@@ -12,9 +17,10 @@ var Composite = {};
 (function() {
 
     /**
-     * Description
+     * Creates a new composite. The options parameter is an object that specifies any properties you wish to override the defaults.
+     * See the properites section below for detailed information on what you can pass via the `options` object.
      * @method create
-     * @param {} options
+     * @param {} [options]
      * @return {composite} A new composite
      */
     Composite.create = function(options) {
@@ -37,8 +43,8 @@ var Composite = {};
      * @method setModified
      * @param {composite} composite
      * @param {boolean} isModified
-     * @param {boolean} updateParents
+     * @param {boolean} [updateParents=false]
-     * @param {boolean} updateChildren
+     * @param {boolean} [updateChildren=false]
      */
     Composite.setModified = function(composite, isModified, updateParents, updateChildren) {
         composite.isModified = isModified;
@@ -95,7 +101,7 @@ var Composite = {};
      * @method remove
      * @param {composite} composite
      * @param {} object
-     * @param {boolean} deep
+     * @param {boolean} [deep=false]
      * @return {composite} The original composite with the objects removed
      */
     Composite.remove = function(composite, object, deep) {
@@ -126,7 +132,7 @@ var Composite = {};
     };
 
     /**
-     * Description
+     * Adds a composite to the given composite
      * @method addComposite
      * @param {composite} compositeA
      * @param {composite} compositeB
@@ -144,7 +150,7 @@ var Composite = {};
      * @method removeComposite
      * @param {composite} compositeA
      * @param {composite} compositeB
-     * @param {boolean} deep
+     * @param {boolean} [deep=false]
      * @return {composite} The original compositeA with the composite removed
      */
     Composite.removeComposite = function(compositeA, compositeB, deep) {
@@ -177,7 +183,7 @@ var Composite = {};
     };
 
     /**
-     * Description
+     * Adds a body to the given composite
      * @method addBody
      * @param {composite} composite
      * @param {body} body
@@ -194,7 +200,7 @@ var Composite = {};
      * @method removeBody
      * @param {composite} composite
      * @param {body} body
-     * @param {boolean} deep
+     * @param {boolean} [deep=false]
      * @return {composite} The original composite with the body removed
      */
     Composite.removeBody = function(composite, body, deep) {
@@ -227,7 +233,7 @@ var Composite = {};
     };
 
     /**
-     * Description
+     * Adds a constraint to the given composite
      * @method addConstraint
      * @param {composite} composite
      * @param {constraint} constraint
@@ -244,7 +250,7 @@ var Composite = {};
      * @method removeConstraint
      * @param {composite} composite
      * @param {constraint} constraint
-     * @param {boolean} deep
+     * @param {boolean} [deep=false]
      * @return {composite} The original composite with the constraint removed
      */
     Composite.removeConstraint = function(composite, constraint, deep) {
@@ -281,7 +287,7 @@ var Composite = {};
      * @method clear
      * @param {world} world
      * @param {boolean} keepStatic
-     * @param {boolean} deep
+     * @param {boolean} [deep=false]
      */
     Composite.clear = function(composite, keepStatic, deep) {
         if (deep) {
@@ -416,4 +422,81 @@ var Composite = {};
         return composite;
     };
 
+    /*
+    *
+    *  Properties Documentation
+    *
+    */
+
+    /**
+     * An integer `Number` uniquely identifying number generated in `Composite.create` by `Common.nextId`.
+     *
+     * @property id
+     * @type number
+     */
+
+    /**
+     * A `String` denoting the type of object.
+     *
+     * @property type
+     * @type string
+     * @default "composite"
+     */
+
+    /**
+     * An arbitrary `String` name to help the user identify and manage composites.
+     *
+     * @property label
+     * @type string
+     * @default "Composite"
+     */
+
+    /**
+     * A flag that specifies whether the composite has been modified during the current step.
+     * Most `Matter.Composite` methods will automatically set this flag to `true` to inform the engine of changes to be handled.
+     * If you need to change it manually, you should use the `Composite.setModified` method.
+     *
+     * @property isModified
+     * @type boolean
+     * @default false
+     */
+
+    /**
+     * The `Composite` that is the parent of this composite. It is automatically managed by the `Matter.Composite` methods.
+     *
+     * @property parent
+     * @type composite
+     * @default null
+     */
+
+    /**
+     * An array of `Body` that are _direct_ children of this composite.
+     * To add or remove bodies you should use `Composite.add` and `Composite.remove` methods rather than directly modifying this property.
+     * If you wish to recursively find all descendants, you should use the `Composite.allBodies` method.
+     *
+     * @property bodies
+     * @type body[]
+     * @default []
+     */
+
+    /**
+     * An array of `Constraint` that are _direct_ children of this composite.
+     * To add or remove constraints you should use `Composite.add` and `Composite.remove` methods rather than directly modifying this property.
+     * If you wish to recursively find all descendants, you should use the `Composite.allConstraints` method.
+     *
+     * @property constraints
+     * @type constraint[]
+     * @default []
+     */
+
+    /**
+     * An array of `Composite` that are _direct_ children of this composite.
+     * To add or remove composites you should use `Composite.add` and `Composite.remove` methods rather than directly modifying this property.
+     * If you wish to recursively find all descendants, you should use the `Composite.allComposites` method.
+     *
+     * @property composites
+     * @type composite[]
+     * @default []
+     */
+
 })();

src/body/World.js

@@ -1,4 +1,10 @@
 /**
+* The `Matter.World` module contains methods for creating and manipulating the world composite.
+* A `Matter.World` is a `Matter.Composite` body, which is a collection of `Matter.Body`, `Matter.Constraint` and other `Matter.Composite`.
+* A `Matter.World` has a few additional properties including `gravity` and `bounds`.
+* 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.
 *
@@ -10,7 +16,8 @@ var World = {};
 (function() {
 
     /**
-     * Description
+     * Creates a new world composite. The options parameter is an object that specifies any properties you wish to override the defaults.
+     * See the properites section below for detailed information on what you can pass via the `options` object.
      * @method create
      * @constructor
      * @param {} options
@@ -35,14 +42,14 @@ var World = {};
     // see src/module/Outro.js for these aliases:
     
     /**
-     * An alias for Composite.clear since World is also a Composite (see Outro.js)
+     * An alias for Composite.clear since World is also a Composite
      * @method clear
      * @param {world} world
      * @param {boolean} keepStatic
      */
 
     /**
-     * An alias for Composite.add since World is also a Composite (see Outro.js)
+     * An alias for Composite.add since World is also a Composite
      * @method addComposite
      * @param {world} world
      * @param {composite} composite
@@ -50,7 +57,7 @@ var World = {};
      */
     
      /**
-      * An alias for Composite.addBody since World is also a Composite (see Outro.js)
+      * An alias for Composite.addBody since World is also a Composite
       * @method addBody
       * @param {world} world
       * @param {body} body
@@ -58,7 +65,7 @@ var World = {};
       */
 
      /**
-      * An alias for Composite.addConstraint since World is also a Composite (see Outro.js)
+      * An alias for Composite.addConstraint since World is also a Composite
       * @method addConstraint
       * @param {world} world
       * @param {constraint} constraint

src/collision/Query.js

@@ -1,5 +1,5 @@
 /**
-* Functions for performing collision queries
+* The `Matter.Query` module contains methods for performing collision queries.
 *
 * @class Query
 */
@@ -14,6 +14,7 @@ var Query = {};
      * @param {body[]} bodies
      * @param {vector} startPoint
      * @param {vector} endPoint
+     * @param {number} [rayWidth]
      * @return {object[]} Collisions
      */
     Query.ray = function(bodies, startPoint, endPoint, rayWidth) {
@@ -42,11 +43,11 @@ var Query = {};
     };
 
     /**
-     * Returns all bodies whose bounds are inside (or outside if set) the given set of bounds, from the given set of bodies
+     * Returns all bodies whose bounds are inside (or outside if set) the given set of bounds, from the given set of bodies.
      * @method region
      * @param {body[]} bodies
      * @param {bounds} bounds
-     * @param {bool} outside
+     * @param {bool} [outside=false]
      * @return {body[]} The bodies matching the query
      */
     Query.region = function(bodies, bounds, outside) {

src/constraint/Constraint.js

@@ -1,4 +1,8 @@
 /**
+* The `Matter.Constraint` module contains methods for creating and manipulating constraints.
+* Constraints are used for specifying that a fixed distance must be maintained between two bodies (or a body and a fixed world-space position).
+* The stiffness of constraints can be modified to create springs or elastic.
+*
 * 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.
 *
@@ -21,7 +25,9 @@ var Constraint = {};
         _minDifference = 0.001;
 
     /**
-     * Description
+     * Creates a new constraint.
+     * All properties have default values, and many are pre-calculated automatically based on other properties.
+     * See the properites section below for detailed information on what you can pass via the `options` object.
      * @method create
      * @param {} options
      * @return {constraint} constraint
@@ -65,6 +71,7 @@ var Constraint = {};
 
     /**
      * Description
+     * @private
      * @method solveAll
      * @param {constraint[]} constraints
      * @param {number} timeScale
@@ -77,6 +84,7 @@ var Constraint = {};
 
     /**
      * Description
+     * @private
      * @method solve
      * @param {constraint} constraint
      * @param {number} timeScale
@@ -231,6 +239,7 @@ var Constraint = {};
 
     /**
      * Performs body updates required after solving constraints
+     * @private
      * @method postSolveAll
      * @param {body[]} bodies
      */
@@ -255,4 +264,116 @@ var Constraint = {};
         }
     };
 
+    /*
+    *
+    *  Properties Documentation
+    *
+    */
+
+    /**
+     * An integer `Number` uniquely identifying number generated in `Composite.create` by `Common.nextId`.
+     *
+     * @property id
+     * @type number
+     */
+
+    /**
+     * A `String` denoting the type of object.
+     *
+     * @property type
+     * @type string
+     * @default "constraint"
+     */
+
+    /**
+     * An arbitrary `String` name to help the user identify and manage bodies.
+     *
+     * @property label
+     * @type string
+     * @default "Constraint"
+     */
+
+    /**
+     * An `Object` that defines the rendering properties to be consumed by the module `Matter.Render`.
+     *
+     * @property render
+     * @type object
+     */
+
+    /**
+     * A flag that indicates if the constraint should be rendered.
+     *
+     * @property render.visible
+     * @type boolean
+     * @default true
+     */
+
+    /**
+     * A `Number` that defines the line width to use when rendering the constraint outline.
+     * A value of `0` means no outline will be rendered.
+     *
+     * @property render.lineWidth
+     * @type number
+     * @default 2
+     */
+
+    /**
+     * A `String` that defines the stroke style to use when rendering the constraint outline.
+     * It is the same as when using a canvas, so it accepts CSS style property values.
+     *
+     * @property render.strokeStyle
+     * @type string
+     * @default a random colour
+     */
+
+    /**
+     * The first possible `Body` that this constraint is attached to.
+     *
+     * @property bodyA
+     * @type body
+     * @default null
+     */
+
+    /**
+     * The second possible `Body` that this constraint is attached to.
+     *
+     * @property bodyB
+     * @type body
+     * @default null
+     */
+
+    /**
+     * A `Vector` that specifies the offset of the constraint from center of the `constraint.bodyA` if defined, otherwise a world-space position.
+     *
+     * @property pointA
+     * @type vector
+     * @default { x: 0, y: 0 }
+     */
+
+    /**
+     * A `Vector` that specifies the offset of the constraint from center of the `constraint.bodyA` if defined, otherwise a world-space position.
+     *
+     * @property pointB
+     * @type vector
+     * @default { x: 0, y: 0 }
+     */
+
+    /**
+     * A `Number` that specifies the stiffness of the constraint, i.e. the rate at which it returns to its resting `constraint.length`.
+     * A value of `1` means the constraint should be very stiff.
+     * A value of `0.2` means the constraint acts like a soft spring.
+     *
+     * @property stiffness
+     * @type number
+     * @default 1
+     */
+
+    /**
+     * A `Number` that specifies the target resting length of the constraint. 
+     * It is calculated automatically in `Constraint.create` from intial positions of the `constraint.bodyA` and `constraint.bodyB`.
+     *
+     * @property length
+     * @type number
+     */
+
 })();

src/constraint/MouseConstraint.js

@@ -1,4 +1,7 @@
 /**
+* The `Matter.MouseConstraint` module contains methods for creating mouse constraints.
+* Mouse constraints are used for allowing user interaction, providing the ability to move bodies via the mouse or touch.
+*
 * 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.
 *
@@ -10,7 +13,9 @@ var MouseConstraint = {};
 (function() {
 
     /**
-     * Description
+     * Creates a new mouse constraint.
+     * All properties have default values, and many are pre-calculated automatically based on other properties.
+     * See the properites section below for detailed information on what you can pass via the `options` object.
      * @method create
      * @param {engine} engine
      * @param {} options
@@ -51,7 +56,8 @@ var MouseConstraint = {};
     };
 
     /**
-     * Description
+     * Updates the given mouse constraint.
+     * @private
      * @method update
      * @param {MouseConstraint} mouseConstraint
      * @param {body[]} bodies
@@ -85,4 +91,49 @@ var MouseConstraint = {};
         }
     };
 
+    /*
+    *
+    *  Properties Documentation
+    *
+    */
+
+    /**
+     * A `String` denoting the type of object.
+     *
+     * @property type
+     * @type string
+     * @default "constraint"
+     */
+
+    /**
+     * The `Mouse` instance in use.
+     *
+     * @property mouse
+     * @type mouse
+     * @default engine.input.mouse
+     */
+
+    /**
+     * The `Body` that is currently being moved by the user, or `null` if no body.
+     *
+     * @property dragBody
+     * @type body
+     * @default null
+     */
+
+    /**
+     * The `Vector` offset at which the drag started relative to the `dragBody`, if any.
+     *
+     * @property dragPoint
+     * @type body
+     * @default null
+     */
+
+    /**
+     * The `Constraint` object that is used to move the body during interaction.
+     *
+     * @property constraint
+     * @type constraint
+     */
+
 })();

src/core/Engine.js

@@ -1,12 +1,13 @@
 /**
+* The `Matter.Engine` module contains methods for creating and manipulating engines.
+* An engine is a controller that manages updating and rendering the simulation of the 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.
 *
 * @class Engine
 */
 
-// TODO: viewports
-
 var Engine = {};
 
 (function() {
@@ -20,10 +21,12 @@ var Engine = {};
                                       || function(callback){ window.setTimeout(function() { callback(Common.now()); }, _delta); };
    
     /**
-     * Description
+     * Creates a new engine. The options parameter is an object that specifies any properties you wish to override the defaults.
+     * All properties have default values, and many are pre-calculated automatically based on other properties.
+     * See the properites section below for detailed information on what you can pass via the `options` object.
      * @method create
      * @param {HTMLElement} element
-     * @param {object} options
+     * @param {object} [options]
      * @return {engine} engine
      */
     Engine.create = function(element, options) {
@@ -178,8 +181,7 @@ var Engine = {};
      * @method update
      * @param {engine} engine
      * @param {number} delta
-     * @param {number} correction
+     * @param {number} [correction]
-     * @return engine
      */
     Engine.update = function(engine, delta, correction) {
         correction = (typeof correction !== 'undefined') ? correction : 1;
@@ -298,7 +300,7 @@ var Engine = {};
     };
     
     /**
-     * Description
+     * Merges two engines by keeping the configuration of `engineA` but replacing the world with the one from `engineB`.
      * @method merge
      * @param {engine} engineA
      * @param {engine} engineB
@@ -322,7 +324,7 @@ var Engine = {};
     };
 
     /**
-     * Description
+     * Clears the engine including the world, pairs and broadphase.
      * @method clear
      * @param {engine} engine
      */
@@ -538,4 +540,125 @@ var Engine = {};
     * @param {} event.name The name of the event
     */
 
+    /*
+    *
+    *  Properties Documentation
+    *
+    */
+
+    /**
+     * A flag that specifies whether the engine is running or not.
+     *
+     * @property enabled
+     * @type boolean
+     * @default true
+     */
+
+    /**
+     * An integer `Number` that specifies the number of position iterations to perform each update.
+     * The higher the value, the higher quality the simulation will be at the expense of performance.
+     *
+     * @property positionIterations
+     * @type number
+     * @default 6
+     */
+
+    /**
+     * An integer `Number` that specifies the number of velocity iterations to perform each update.
+     * The higher the value, the higher quality the simulation will be at the expense of performance.
+     *
+     * @property velocityIterations
+     * @type number
+     * @default 4
+     */
+
+    /**
+     * An integer `Number` that specifies the number of constraint iterations to perform each update.
+     * The higher the value, the higher quality the simulation will be at the expense of performance.
+     * The default value of `2` is usually very adequate.
+     *
+     * @property constraintIterations
+     * @type number
+     * @default 2
+     */
+
+    /**
+     * A flag that specifies whether the engine should allow sleeping via the `Matter.Sleeping` module.
+     * Sleeping can improve stability and performance, but often at the expense of accuracy.
+     *
+     * @property enableSleeping
+     * @type boolean
+     * @default false
+     */
+
+    /**
+     * An `Object` containing properties regarding the timing systems of the engine. 
+     *
+     * @property timing
+     * @type object
+     */
+
+    /**
+     * A `Number` that specifies the global scaling factor of time for all bodies.
+     * A value of `0` freezes the simulation.
+     * A value of `0.1` gives a slow-motion effect.
+     * A value of `1.2` gives a speed-up effect.
+     *
+     * @property timing.timeScale
+     * @type number
+     * @default 1
+     */
+
+    /**
+     * A `Number` that specifies the current simulation-time in milliseconds starting from `0`. 
+     * It is incremented on every `Engine.update` by the `timing.delta`. 
+     *
+     * @property timing.timestamp
+     * @type number
+     * @default 0
+     */
+
+    /**
+     * A `Number` that specifies the time step between updates in milliseconds.
+     * If `engine.timing.isFixed` is set to `true`, then `delta` is fixed.
+     * If it is `false`, then `delta` can dynamically change to maintain the correct apparant simulation speed.
+     *
+     * @property timing.delta
+     * @type number
+     * @default 1000 / 60
+     */
+
+    /**
+     * A `Number` that specifies the time correction factor to apply to the current timestep.
+     * It is automatically handled when using `Engine.run`, but is also only optional even if you use your own game loop.
+     * The value is defined as `delta / lastDelta`, i.e. the percentage change of `delta` between steps.
+     * This value is always `1` (no correction) when frame rate is constant or `engine.timing.isFixed` is `true`.
+     * If the framerate and hence `delta` are changing, then correction should be applied to the current update to account for the change.
+     * See the paper on <a href="http://lonesock.net/article/verlet.html">Time Corrected Verlet</a> for more information.
+     *
+     * @property timing.correction
+     * @type number
+     * @default 1
+     */
+
+    /**
+     * An instance of a `Render` controller. The default value is a `Matter.Render` instance created by `Engine.create`.
+     * One may also develop a custom renderer module based on `Matter.Render` and pass an instance of it to `Engine.create` via `options.render`.
+     *
+     * A minimal custom renderer object must define at least three functions: `create`, `clear` and `world` (see `Matter.Render`).
+     * It is also possible to instead pass the _module_ reference via `options.render.controller` and `Engine.create` will instantiate one for you.
+     *
+     * @property render
+     * @type render
+     * @default a Matter.Render instance
+     */
+
+    /**
+     * A `World` composite object that will contain all simulated bodies and constraints.
+     *
+     * @property world
+     * @type world
+     * @default a Matter.World instance
+     */
+
 })();

src/core/Events.js

@@ -10,7 +10,7 @@ var Events = {};
 (function() {
 
     /**
-     * Subscribes a callback function to the given object's eventName
+     * Subscribes a callback function to the given object's `eventName`.
      * @method on
      * @param {} object
      * @param {string} eventNames
@@ -31,7 +31,7 @@ var Events = {};
     };
 
     /**
-     * Removes the given event callback. If no callback, clears all callbacks in eventNames. If no eventNames, clears all events.
+     * Removes the given event callback. If no callback, clears all callbacks in `eventNames`. If no `eventNames`, clears all events.
      * @method off
      * @param {} object
      * @param {string} eventNames
@@ -67,7 +67,7 @@ var Events = {};
     };
 
     /**
-     * Fires all the callbacks subscribed to the given object's eventName, in the order they subscribed, if any
+     * Fires all the callbacks subscribed to the given object's `eventName`, in the order they subscribed, if any.
      * @method trigger
      * @param {} object
      * @param {string} eventNames

src/factory/Bodies.js

@@ -1,4 +1,7 @@
 /**
+* The `Matter.Bodies` module contains factory methods for creating rigid body models 
+* with commonly used body configurations (such as rectangles, circles and other polygons).
+*
 * 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.
 *
@@ -12,13 +15,15 @@ var Bodies = {};
 (function() {
 
     /**
-     * Description
+     * Creates a new rigid body model with a rectangle hull. 
+     * The options parameter is an object that specifies any properties you wish to override the defaults.
+     * See the properites section of the `Matter.Body` module for detailed information on what you can pass via the `options` object.
      * @method rectangle
      * @param {number} x
      * @param {number} y
      * @param {number} width
      * @param {number} height
-     * @param {object} options
+     * @param {object} [options]
      * @return {body} A new rectangle body
      */
     Bodies.rectangle = function(x, y, width, height, options) {
@@ -41,14 +46,16 @@ var Bodies = {};
     };
     
     /**
-     * Description
+     * Creates a new rigid body model with a trapezoid hull. 
+     * The options parameter is an object that specifies any properties you wish to override the defaults.
+     * See the properites section of the `Matter.Body` module for detailed information on what you can pass via the `options` object.
      * @method trapezoid
      * @param {number} x
      * @param {number} y
      * @param {number} width
      * @param {number} height
      * @param {number} slope
-     * @param {object} options
+     * @param {object} [options]
      * @return {body} A new trapezoid body
      */
     Bodies.trapezoid = function(x, y, width, height, slope, options) {
@@ -78,12 +85,14 @@ var Bodies = {};
     };
 
     /**
-     * Description
+     * Creates a new rigid body model with a circle hull. 
+     * The options parameter is an object that specifies any properties you wish to override the defaults.
+     * See the properites section of the `Matter.Body` module for detailed information on what you can pass via the `options` object.
      * @method circle
      * @param {number} x
      * @param {number} y
      * @param {number} radius
-     * @param {object} options
+     * @param {object} [options]
      * @param {number} maxSides
      * @return {body} A new circle body
      */
@@ -107,13 +116,15 @@ var Bodies = {};
     };
 
     /**
-     * Description
+     * Creates a new rigid body model with a regular polygon hull with the given number of sides. 
+     * The options parameter is an object that specifies any properties you wish to override the defaults.
+     * See the properites section of the `Matter.Body` module for detailed information on what you can pass via the `options` object.
      * @method polygon
      * @param {number} x
      * @param {number} y
      * @param {number} sides
      * @param {number} radius
-     * @param {object} options
+     * @param {object} [options]
      * @return {body} A new regular polygon body
      */
     Bodies.polygon = function(x, y, sides, radius, options) {

src/geometry/Vector.js

@@ -1,4 +1,8 @@
 /**
+* The `Matter.Vector` module contains methods for creating and manipulating vectors.
+* Vectors are the basis of all the geometry related operations in the engine.
+* A `Matter.Vector` object is of the form `{ x: 0, y: 0 }`.
+*
 * 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.
 *
@@ -12,7 +16,7 @@ var Vector = {};
 (function() {
 
     /**
-     * Description
+     * Returns the magnitude (length) of a vector.
      * @method magnitude
      * @param {vector} vector
      * @return {number} The magnitude of the vector
@@ -22,7 +26,7 @@ var Vector = {};
     };
 
     /**
-     * Description
+     * Returns the magnitude (length) of a vector (therefore saving a `sqrt` operation).
      * @method magnitudeSquared
      * @param {vector} vector
      * @return {number} The squared magnitude of the vector
@@ -32,11 +36,11 @@ var Vector = {};
     };
 
     /**
-     * Description
+     * Rotates the vector about (0, 0) by specified angle.
      * @method rotate
      * @param {vector} vector
      * @param {number} angle
-     * @return {vector} A new vector rotated
+     * @return {vector} A new vector rotated about (0, 0)
      */
     Vector.rotate = function(vector, angle) {
         var cos = Math.cos(angle), sin = Math.sin(angle);
@@ -47,7 +51,7 @@ var Vector = {};
     };
 
     /**
-     * Description
+     * Rotates the vector about a specified point by specified angle.
      * @method rotateAbout
      * @param {vector} vector
      * @param {number} angle
@@ -63,7 +67,7 @@ var Vector = {};
     };
 
     /**
-     * Description
+     * Normalises a vector (such that its magnitude is `1`).
      * @method normalise
      * @param {vector} vector
      * @return {vector} A new vector normalised
@@ -76,7 +80,7 @@ var Vector = {};
     };
 
     /**
-     * Description
+     * Returns the dot-product of two vectors.
      * @method dot
      * @param {vector} vectorA
      * @param {vector} vectorB
@@ -87,7 +91,7 @@ var Vector = {};
     };
 
     /**
-     * Description
+     * Returns the cross-product of two vectors.
      * @method cross
      * @param {vector} vectorA
      * @param {vector} vectorB
@@ -98,29 +102,29 @@ var Vector = {};
     };
 
     /**
-     * Description
+     * Adds the two vectors.
      * @method add
      * @param {vector} vectorA
      * @param {vector} vectorB
-     * @return {vector} A new vector added
+     * @return {vector} A new vector of vectorA and vectorB added
      */
     Vector.add = function(vectorA, vectorB) {
         return { x: vectorA.x + vectorB.x, y: vectorA.y + vectorB.y };
     };
 
     /**
-     * Description
+     * Subtracts the two vectors.
      * @method sub
      * @param {vector} vectorA
      * @param {vector} vectorB
-     * @return {vector} A new vector subtracted
+     * @return {vector} A new vector of vectorA and vectorB subtracted
      */
     Vector.sub = function(vectorA, vectorB) {
         return { x: vectorA.x - vectorB.x, y: vectorA.y - vectorB.y };
     };
 
     /**
-     * Description
+     * Multiplies a vector and a scalar.
      * @method mult
      * @param {vector} vector
      * @param {number} scalar
@@ -131,7 +135,7 @@ var Vector = {};
     };
 
     /**
-     * Description
+     * Divides a vector and a scalar.
      * @method div
      * @param {vector} vector
      * @param {number} scalar
@@ -142,10 +146,10 @@ var Vector = {};
     };
 
     /**
-     * Description
+     * Returns the perpendicular vector. Set `negate` to true for the perpendicular in the opposite direction.
      * @method perp
      * @param {vector} vector
-     * @param {bool} negate
+     * @param {bool} [negate=false]
      * @return {vector} The perpendicular vector
      */
     Vector.perp = function(vector, negate) {
@@ -154,7 +158,7 @@ var Vector = {};
     };
 
     /**
-     * Description
+     * Negates both components of a vector such that it points in the opposite direction.
      * @method neg
      * @param {vector} vector
      * @return {vector} The negated vector
@@ -164,7 +168,7 @@ var Vector = {};
     };
 
     /**
-     * Returns the angle in radians between the two vectors relative to the x-axis
+     * Returns the angle in radians between the two vectors relative to the x-axis.
      * @method angle
      * @param {vector} vectorA
      * @param {vector} vectorB

src/geometry/Vertices.js

@@ -1,4 +1,8 @@
 /**
+* The `Matter.Vertices` module contains methods for creating and manipulating sets of vertices.
+* A set of vertices is an array of `Matter.Vector` with additional indexing properties inserted by `Vertices.create`.
+* A `Matter.Body` maintains a set of vertices to represent the shape of the object (its convex hull).
+*
 * 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.
 *
@@ -12,7 +16,13 @@ var Vertices = {};
 (function() {
 
     /**
-     * Description
+     * Creates a new set of `Matter.Body` compatible vertices.
+     * The `vertices` argument accepts an array of `Matter.Vector` orientated around the origin `(0, 0)`, for example:
+     *
+     *     [{ x: 0, y: 0 }, { x: 25, y: 50 }, { x: 50, y: 0 }]
+     *
+     * The `Vertices.create` method then inserts additional indexing properties required for efficient collision detection routines.
+     *
      * @method create
      * @param {vertices} vertices
      * @param {body} body
@@ -25,7 +35,7 @@ var Vertices = {};
     };
 
     /**
-     * Description
+     * Parses a _simple_ SVG-style path into a set of `Matter.Vector` points.
      * @method fromPath
      * @param {string} path
      * @return {vertices} vertices
@@ -42,7 +52,7 @@ var Vertices = {};
     };
 
     /**
-     * Description
+     * Returns the centre (centroid) of the set of vertices.
      * @method centre
      * @param {vertices} vertices
      * @return {vector} The centre point
@@ -65,7 +75,7 @@ var Vertices = {};
     };
 
     /**
-     * Description
+     * Returns the area of the set of vertices.
      * @method area
      * @param {vertices} vertices
      * @param {bool} signed
@@ -87,11 +97,11 @@ var Vertices = {};
     };
 
     /**
-     * Description
+     * Returns the moment of inertia (second moment of area) of the set of vertices given the total mass.
      * @method inertia
      * @param {vertices} vertices
      * @param {number} mass
-     * @return {number} The polygon's moment of inertia, using second moment of area
+     * @return {number} The polygon's moment of inertia
      */
     Vertices.inertia = function(vertices, mass) {
         var numerator = 0,
@@ -113,7 +123,7 @@ var Vertices = {};
     };
 
     /**
-     * Description
+     * Translates the set of vertices in-place.
      * @method translate
      * @param {vertices} vertices
      * @param {vector} vector
@@ -135,7 +145,7 @@ var Vertices = {};
     };
 
     /**
-     * Description
+     * Rotates the set of vertices in-place.
      * @method rotate
      * @param {vertices} vertices
      * @param {number} angle
@@ -159,7 +169,7 @@ var Vertices = {};
     };
 
     /**
-     * Description
+     * Returns `true` if the `point` is inside the set of `vertices`.
      * @method contains
      * @param {vertices} vertices
      * @param {vector} point
@@ -178,7 +188,7 @@ var Vertices = {};
     };
 
     /**
-     * Scales the vertices from a point (default is centre)
+     * Scales the vertices from a point (default is centre) in-place.
      * @method scale
      * @param {vertices} vertices
      * @param {number} scaleX

src/render/Render.js

@@ -1,21 +1,25 @@
 /**
-* See [Demo.js](https://github.com/liabru/matter-js/blob/master/demo/js/Demo.js) 
+* The `Matter.Render` module is the default `render.controller` used by a `Matter.Engine`.
-* and [DemoMobile.js](https://github.com/liabru/matter-js/blob/master/demo/js/DemoMobile.js) for usage examples.
+* This renderer is HTML5 canvas based and supports a number of drawing options including sprites and viewports.
+*
+* It is possible develop a custom renderer module based on `Matter.Render` and pass an instance of it to `Engine.create` via `options.render`.
+* A minimal custom renderer object must define at least three functions: `create`, `clear` and `world` (see `Matter.Render`).
+*
+* See also `Matter.RenderPixi` for an alternate WebGL, scene-graph based renderer.
 *
 * @class Render
 */
 
-// TODO: viewports
-// TODO: two.js, pixi.js
-
 var Render = {};
 
 (function() {
     
     /**
-     * Description
+     * Creates a new renderer. The options parameter is an object that specifies any properties you wish to override the defaults.
+     * All properties have default values, and many are pre-calculated automatically based on other properties.
+     * See the properites section below for detailed information on what you can pass via the `options` object.
      * @method create
-     * @param {object} options
+     * @param {object} [options]
      * @return {render} A new renderer
      */
     Render.create = function(options) {
@@ -103,7 +107,8 @@ var Render = {};
     };
 
     /**
-     * Description
+     * Renders the given `engine`'s `Matter.World` object.
+     * This is the entry point for all rendering and should be called every time the scene changes.
      * @method world
      * @param {engine} engine
      */
@@ -213,6 +218,7 @@ var Render = {};
 
     /**
      * Description
+     * @private
      * @method debug
      * @param {engine} engine
      * @param {RenderingContext} context
@@ -269,6 +275,7 @@ var Render = {};
 
     /**
      * Description
+     * @private
      * @method constraints
      * @param {constraint[]} constraints
      * @param {RenderingContext} context
@@ -307,6 +314,7 @@ var Render = {};
     
     /**
      * Description
+     * @private
      * @method bodyShadows
      * @param {engine} engine
      * @param {body[]} bodies
@@ -356,6 +364,7 @@ var Render = {};
 
     /**
      * Description
+     * @private
      * @method bodies
      * @param {engine} engine
      * @param {body[]} bodies
@@ -432,6 +441,7 @@ var Render = {};
 
     /**
      * Optimised method for drawing body wireframes in one pass
+     * @private
      * @method bodyWireframes
      * @param {engine} engine
      * @param {body[]} bodies
@@ -466,6 +476,7 @@ var Render = {};
 
     /**
      * Draws body bounds
+     * @private
      * @method bodyBounds
      * @param {engine} engine
      * @param {body[]} bodies
@@ -497,6 +508,7 @@ var Render = {};
 
     /**
      * Draws body angle indicators and axes
+     * @private
      * @method bodyAxes
      * @param {engine} engine
      * @param {body[]} bodies
@@ -544,6 +556,7 @@ var Render = {};
 
     /**
      * Draws body positions
+     * @private
      * @method bodyPositions
      * @param {engine} engine
      * @param {body[]} bodies
@@ -591,6 +604,7 @@ var Render = {};
 
     /**
      * Draws body velocity
+     * @private
      * @method bodyVelocity
      * @param {engine} engine
      * @param {body[]} bodies
@@ -620,6 +634,7 @@ var Render = {};
 
     /**
      * Draws body ids
+     * @private
      * @method bodyIds
      * @param {engine} engine
      * @param {body[]} bodies
@@ -642,6 +657,7 @@ var Render = {};
 
     /**
      * Description
+     * @private
      * @method collisions
      * @param {engine} engine
      * @param {pair[]} pairs
@@ -708,6 +724,7 @@ var Render = {};
 
     /**
      * Description
+     * @private
      * @method grid
      * @param {engine} engine
      * @param {grid} grid
@@ -746,6 +763,7 @@ var Render = {};
 
     /**
      * Description
+     * @private
      * @method inspector
      * @param {inspector} inspector
      * @param {RenderingContext} context
@@ -867,4 +885,88 @@ var Render = {};
         return image;
     };
 
+    /*
+    *
+    *  Properties Documentation
+    *
+    */
+
+    /**
+     * A back-reference to the `Matter.Render` module.
+     *
+     * @property controller
+     * @type render
+     */
+
+    /**
+     * A reference to the element where the canvas is to be inserted (if `render.canvas` has not been specified)
+     *
+     * @property element
+     * @type HTMLElement
+     * @default null
+     */
+
+    /**
+     * The canvas element to render to. If not specified, one will be created if `render.element` has been specified.
+     *
+     * @property canvas
+     * @type HTMLCanvasElement
+     * @default null
+     */
+
+    /**
+     * The configuration options of the renderer.
+     *
+     * @property options
+     * @type {}
+     */
+
+    /**
+     * The target width in pixels of the `render.canvas` to be created.
+     *
+     * @property options.width
+     * @type number
+     * @default 800
+     */
+
+    /**
+     * The target height in pixels of the `render.canvas` to be created.
+     *
+     * @property options.height
+     * @type number
+     * @default 600
+     */
+
+    /**
+     * A flag that specifies if `render.bounds` should be used when rendering.
+     *
+     * @property options.hasBounds
+     * @type boolean
+     * @default false
+     */
+
+    /**
+     * A `Bounds` object that specifies the drawing view region. 
+     * Rendering will be automatically transformed and scaled to fit within the canvas size (`render.options.width` and `render.options.height`).
+     * This allows for creating views that can pan or zoom around the scene.
+     * You must also set `render.options.hasBounds` to `true` to enable bounded rendering.
+     *
+     * @property bounds
+     * @type bounds
+     */
+
+    /**
+     * The 2d rendering context from the `render.canvas` element.
+     *
+     * @property context
+     * @type CanvasRenderingContext2D
+     */
+
+    /**
+     * The sprite texture cache.
+     *
+     * @property textures
+     * @type {}
+     */
+
 })();