From a70fb6aee96d996080f8703a73cdc220f810df43 Mon Sep 17 00:00:00 2001
From: samme <samme@users.noreply.github.com>
Date: Mon, 23 Apr 2018 17:48:15 -0700
Subject: [PATCH] Add docs for Arcade Physics

---
 src/physics/arcade/ArcadePhysics.js |  24 +-
 src/physics/arcade/Body.js          | 407 +++++++++++++++-------------
 src/physics/arcade/PhysicsGroup.js  |  45 +--
 src/physics/arcade/World.js         | 201 ++++++++------
 4 files changed, 381 insertions(+), 296 deletions(-)

diff --git a/src/physics/arcade/ArcadePhysics.js b/src/physics/arcade/ArcadePhysics.js
index b8221b012..638a70656 100644
--- a/src/physics/arcade/ArcadePhysics.js
+++ b/src/physics/arcade/ArcadePhysics.js
@@ -229,7 +229,7 @@ var ArcadePhysics = new Class({
     },
 
     /**
-     * Sets the acceleration.x/y property on the game object so it will move towards the x/y coordinates at the given speed (in pixels per second sq.)
+     * Sets the acceleration.x/y property on the game object so it will move towards the x/y coordinates at the given rate (in pixels per second squared)
      *
      * You must give a maximum speed value, beyond which the game object won't go any faster.
      *
@@ -242,7 +242,7 @@ var ArcadePhysics = new Class({
      * @param {Phaser.GameObjects.GameObject} gameObject - Any Game Object with an Arcade Physics body.
      * @param {number} x - The x coordinate to accelerate towards.
      * @param {number} y - The y coordinate to accelerate towards.
-     * @param {number} [speed=60] - The speed it will accelerate in pixels per second.
+     * @param {number} [speed=60] - The acceleration (change in speed) in pixels per second squared.
      * @param {number} [xSpeedMax=500] - The maximum x velocity the game object can reach.
      * @param {number} [ySpeedMax=500] - The maximum y velocity the game object can reach.
      *
@@ -265,7 +265,7 @@ var ArcadePhysics = new Class({
     },
 
     /**
-     * Sets the acceleration.x/y property on the game object so it will move towards the x/y coordinates at the given speed (in pixels per second sq.)
+     * Sets the acceleration.x/y property on the game object so it will move towards the x/y coordinates at the given rate (in pixels per second squared)
      *
      * You must give a maximum speed value, beyond which the game object won't go any faster.
      *
@@ -277,7 +277,7 @@ var ArcadePhysics = new Class({
      *
      * @param {Phaser.GameObjects.GameObject} gameObject - Any Game Object with an Arcade Physics body.
      * @param {Phaser.GameObjects.GameObject} destination - The Game Object to move towards. Can be any object but must have visible x/y properties.
-     * @param {number} [speed=60] - The speed it will accelerate in pixels per second.
+     * @param {number} [speed=60] - The acceleration (change in speed) in pixels per second squared.
      * @param {number} [xSpeedMax=500] - The maximum x velocity the game object can reach.
      * @param {number} [ySpeedMax=500] - The maximum y velocity the game object can reach.
      *
@@ -289,7 +289,7 @@ var ArcadePhysics = new Class({
     },
 
     /**
-     * From a set of points or display objects, find the one closest to a source point or object.
+     * Finds the Body closest to a source point or object.
      *
      * @method Phaser.Physics.Arcade.ArcadePhysics#closest
      * @since 3.0.0
@@ -323,7 +323,7 @@ var ArcadePhysics = new Class({
     },
 
     /**
-     * From a set of points or display objects, find the one farthest from a source point or object.
+     * Finds the Body farthest from a source point or object.
      *
      * @method Phaser.Physics.Arcade.ArcadePhysics#furthest
      * @since 3.0.0
@@ -417,14 +417,14 @@ var ArcadePhysics = new Class({
     },
 
     /**
-     * Given the angle (in degrees) and speed calculate the velocity and return it as a Point object, or set it to the given point object.
-     * One way to use this is: velocityFromAngle(angle, 200, sprite.velocity) which will set the values directly to the sprites velocity and not create a new Point object.
+     * Given the angle (in degrees) and speed calculate the velocity and return it as a vector, or set it to the given vector object.
+     * One way to use this is: velocityFromAngle(angle, 200, sprite.body.velocity) which will set the values directly to the sprite's velocity and not create a new vector object.
      *
      * @method Phaser.Physics.Arcade.ArcadePhysics#velocityFromAngle
      * @since 3.0.0
      *
      * @param {number} angle - The angle in degrees calculated in clockwise positive direction (down = 90 degrees positive, right = 0 degrees positive, up = 90 degrees negative)
-     * @param {number} [speed=60] - The speed it will move, in pixels per second sq.
+     * @param {number} [speed=60] - The speed it will move, in pixels per second squared.
      * @param {Phaser.Math.Vector2} [vec2] - The Vector2 in which the x and y properties will be set to the calculated velocity.
      *
      * @return {Phaser.Math.Vector2} The Vector2 that stores the velocity.
@@ -438,14 +438,14 @@ var ArcadePhysics = new Class({
     },
 
     /**
-     * Given the rotation (in radians) and speed calculate the velocity and return it as a Point object, or set it to the given point object.
-     * One way to use this is: velocityFromRotation(rotation, 200, sprite.velocity) which will set the values directly to the sprites velocity and not create a new Point object.
+     * Given the rotation (in radians) and speed calculate the velocity and return it as a vector, or set it to the given vector object.
+     * One way to use this is: velocityFromRotation(rotation, 200, sprite.body.velocity) which will set the values directly to the sprite's velocity and not create a new vector object.
      *
      * @method Phaser.Physics.Arcade.ArcadePhysics#velocityFromRotation
      * @since 3.0.0
      *
      * @param {number} rotation - The angle in radians.
-     * @param {number} [speed=60] - The speed it will move, in pixels per second sq.
+     * @param {number} [speed=60] - The speed it will move, in pixels per second squared
      * @param {Phaser.Math.Vector2} [vec2] - The Vector2 in which the x and y properties will be set to the calculated velocity.
      *
      * @return {Phaser.Math.Vector2} The Vector2 that stores the velocity.
diff --git a/src/physics/arcade/Body.js b/src/physics/arcade/Body.js
index 209803ff6..0209047c8 100644
--- a/src/physics/arcade/Body.js
+++ b/src/physics/arcade/Body.js
@@ -16,33 +16,33 @@ var Vector2 = require('../../math/Vector2');
 /**
  * @typedef {object} ArcadeBodyBounds
  *
- * @property {number} x - [description]
- * @property {number} y - [description]
- * @property {number} right - [description]
- * @property {number} bottom - [description]
+ * @property {number} x - The left edge.
+ * @property {number} y - The upper edge.
+ * @property {number} right - The right edge.
+ * @property {number} bottom - The lower edge.
  */
 
 /**
  * @typedef {object} ArcadeBodyCollision
  *
- * @property {boolean} none - [description]
- * @property {boolean} up - [description]
- * @property {boolean} down - [description]
- * @property {boolean} left - [description]
- * @property {boolean} right - [description]
+ * @property {boolean} none - True if the Body is not colliding.
+ * @property {boolean} up - True if the Body is colliding on its upper edge.
+ * @property {boolean} down - True if the Body is colliding on its lower edge.
+ * @property {boolean} left - True if the Body is colliding on its left edge.
+ * @property {boolean} right - True if the Body is colliding on its right edge.
  */
 
 /**
  * @classdesc
- * [description]
+ * A Dynamic Arcade Body.
  *
  * @class Body
  * @memberOf Phaser.Physics.Arcade
  * @constructor
  * @since 3.0.0
  *
- * @param {Phaser.Physics.Arcade.World} world - [description]
- * @param {Phaser.GameObjects.GameObject} gameObject - [description]
+ * @param {Phaser.Physics.Arcade.World} world - The Arcade Physics simulation this Body belongs to.
+ * @param {Phaser.GameObjects.GameObject} gameObject - The Game Object this Body belongs to.
  */
 var Body = new Class({
 
@@ -54,7 +54,7 @@ var Body = new Class({
         var height = (gameObject.height) ? gameObject.height : 64;
 
         /**
-         * [description]
+         * The Arcade Physics simulation this Body belongs to.
          *
          * @name Phaser.Physics.Arcade.Body#world
          * @type {Phaser.Physics.Arcade.World}
@@ -63,7 +63,7 @@ var Body = new Class({
         this.world = world;
 
         /**
-         * [description]
+         * The Game Object this Body belongs to.
          *
          * @name Phaser.Physics.Arcade.Body#gameObject
          * @type {Phaser.GameObjects.GameObject}
@@ -72,7 +72,7 @@ var Body = new Class({
         this.gameObject = gameObject;
 
         /**
-         * [description]
+         * Transformations applied to this Body.
          *
          * @name Phaser.Physics.Arcade.Body#transform
          * @type {object}
@@ -89,7 +89,7 @@ var Body = new Class({
         };
 
         /**
-         * [description]
+         * Whether the Body's boundary is drawn to the debug display.
          *
          * @name Phaser.Physics.Arcade.Body#debugShowBody
          * @type {boolean}
@@ -98,7 +98,7 @@ var Body = new Class({
         this.debugShowBody = world.defaults.debugShowBody;
 
         /**
-         * [description]
+         * Whether the Body's velocity is drawn to the debug display.
          *
          * @name Phaser.Physics.Arcade.Body#debugShowVelocity
          * @type {boolean}
@@ -107,7 +107,7 @@ var Body = new Class({
         this.debugShowVelocity = world.defaults.debugShowVelocity;
 
         /**
-         * [description]
+         * The color of this Body on the debug display.
          *
          * @name Phaser.Physics.Arcade.Body#debugBodyColor
          * @type {integer}
@@ -116,7 +116,7 @@ var Body = new Class({
         this.debugBodyColor = world.defaults.bodyDebugColor;
 
         /**
-         * [description]
+         * Whether this Body is updated by the physics simulation.
          *
          * @name Phaser.Physics.Arcade.Body#enable
          * @type {boolean}
@@ -126,36 +126,40 @@ var Body = new Class({
         this.enable = true;
 
         /**
-         * [description]
+         * Whether this Body's boundary is circular (true) or rectangular (false).
          *
          * @name Phaser.Physics.Arcade.Body#isCircle
          * @type {boolean}
          * @default false
          * @since 3.0.0
+         * @see Phaser.Physics.Arcade.Body#setCircle
          */
         this.isCircle = false;
 
         /**
-         * [description]
+         * The unscaled radius of this Body's boundary (if circular), as set by setCircle, in source pixels.
+         * The true radius (if circular) is equal to halfWidth.
          *
          * @name Phaser.Physics.Arcade.Body#radius
          * @type {number}
          * @default 0
          * @since 3.0.0
+         * @see Phaser.Physics.Arcade.Body#setCircle
          */
         this.radius = 0;
 
         /**
-         * [description]
+         * The offset of this Body's position from its Game Object's position, in source pixels.
          *
          * @name Phaser.Physics.Arcade.Body#offset
          * @type {Phaser.Math.Vector2}
          * @since 3.0.0
+         * @see Phaser.Physics.Arcade.Body#setOffset
          */
         this.offset = new Vector2();
 
         /**
-         * [description]
+         * The position of this Body within the simulation.
          *
          * @name Phaser.Physics.Arcade.Body#position
          * @type {Phaser.Math.Vector2}
@@ -164,7 +168,7 @@ var Body = new Class({
         this.position = new Vector2(gameObject.x, gameObject.y);
 
         /**
-         * [description]
+         * The position of this Body during the previous step.
          *
          * @name Phaser.Physics.Arcade.Body#prev
          * @type {Phaser.Math.Vector2}
@@ -173,7 +177,7 @@ var Body = new Class({
         this.prev = new Vector2(gameObject.x, gameObject.y);
 
         /**
-         * [description]
+         * Whether this Body's rotation is affected by its angular acceleration and velocity.
          *
          * @name Phaser.Physics.Arcade.Body#allowRotation
          * @type {boolean}
@@ -183,7 +187,9 @@ var Body = new Class({
         this.allowRotation = true;
 
         /**
-         * [description]
+         * This body's rotation, in degrees, based on its angular acceleration and velocity.
+         * The Body's rotation controls the `angle` of its Game Object.
+         * It doesn't rotate the Body's boundary, which is always an axis-aligned rectangle or a circle.
          *
          * @name Phaser.Physics.Arcade.Body#rotation
          * @type {number}
@@ -192,7 +198,7 @@ var Body = new Class({
         this.rotation = gameObject.angle;
 
         /**
-         * [description]
+         * The Body's rotation, in degrees, during the previous step.
          *
          * @name Phaser.Physics.Arcade.Body#preRotation
          * @type {number}
@@ -201,38 +207,42 @@ var Body = new Class({
         this.preRotation = gameObject.angle;
 
         /**
-         * [description]
+         * The width of the Body's boundary. If circular, this is also the Body's diameter.
          *
          * @name Phaser.Physics.Arcade.Body#width
          * @type {number}
+         * @default 64
          * @since 3.0.0
          */
         this.width = width;
 
         /**
-         * [description]
+         * The height of the Body's boundary. If circular, this is also the Body's diameter.
          *
          * @name Phaser.Physics.Arcade.Body#height
          * @type {number}
+         * @default 64
          * @since 3.0.0
          */
         this.height = height;
 
         /**
-         * [description]
+         * The unscaled width of the Body, in source pixels. The default is the width of the Body's Game Object's texture frame.
          *
          * @name Phaser.Physics.Arcade.Body#sourceWidth
          * @type {number}
          * @since 3.0.0
+         * @see Phaser.Physics.Arcade.Body#setSize
          */
         this.sourceWidth = width;
 
         /**
-         * [description]
+         * The unscaled height of the Body, in source pixels. The default is the height of the Body's Game Object's texture frame.
          *
          * @name Phaser.Physics.Arcade.Body#sourceHeight
          * @type {number}
          * @since 3.0.0
+         * @see Phaser.Physics.Arcade.Body#setSize
          */
         this.sourceHeight = height;
 
@@ -243,7 +253,7 @@ var Body = new Class({
         }
 
         /**
-         * [description]
+         * Half the Body's width.
          *
          * @name Phaser.Physics.Arcade.Body#halfWidth
          * @type {number}
@@ -252,7 +262,7 @@ var Body = new Class({
         this.halfWidth = Math.abs(width / 2);
 
         /**
-         * [description]
+         * Half the Body's height.
          *
          * @name Phaser.Physics.Arcade.Body#halfHeight
          * @type {number}
@@ -261,7 +271,7 @@ var Body = new Class({
         this.halfHeight = Math.abs(height / 2);
 
         /**
-         * [description]
+         * The center of the Body's boundary. The midpoint of its `position` (top-left corner) and its bottom-right corner.
          *
          * @name Phaser.Physics.Arcade.Body#center
          * @type {Phaser.Math.Vector2}
@@ -270,7 +280,7 @@ var Body = new Class({
         this.center = new Vector2(gameObject.x + this.halfWidth, gameObject.y + this.halfHeight);
 
         /**
-         * [description]
+         * The Body's change in position, in pixels per second.
          *
          * @name Phaser.Physics.Arcade.Body#velocity
          * @type {Phaser.Math.Vector2}
@@ -279,16 +289,17 @@ var Body = new Class({
         this.velocity = new Vector2();
 
         /**
-         * [description]
+         * The Body's calculated change in position, in pixels, at the last step.
          *
          * @name Phaser.Physics.Arcade.Body#newVelocity
          * @type {Phaser.Math.Vector2}
+         * @readOnly
          * @since 3.0.0
          */
         this.newVelocity = new Vector2();
 
         /**
-         * [description]
+         * The Body's absolute maximum change in position, in pixels per step.
          *
          * @name Phaser.Physics.Arcade.Body#deltaMax
          * @type {Phaser.Math.Vector2}
@@ -297,7 +308,7 @@ var Body = new Class({
         this.deltaMax = new Vector2();
 
         /**
-         * [description]
+         * The Body's change in velocity, in pixels per second squared.
          *
          * @name Phaser.Physics.Arcade.Body#acceleration
          * @type {Phaser.Math.Vector2}
@@ -306,7 +317,7 @@ var Body = new Class({
         this.acceleration = new Vector2();
 
         /**
-         * [description]
+         * Whether this Body's velocity is affected by its drag vector.
          *
          * @name Phaser.Physics.Arcade.Body#allowDrag
          * @type {boolean}
@@ -316,7 +327,7 @@ var Body = new Class({
         this.allowDrag = true;
 
         /**
-         * [description]
+         * Absolute loss of velocity due to movement, in pixels per second squared.
          *
          * @name Phaser.Physics.Arcade.Body#drag
          * @type {Phaser.Math.Vector2}
@@ -325,7 +336,7 @@ var Body = new Class({
         this.drag = new Vector2();
 
         /**
-         * [description]
+         * Whether this Body's position is affected by its gravity vector.
          *
          * @name Phaser.Physics.Arcade.Body#allowGravity
          * @type {boolean}
@@ -335,7 +346,8 @@ var Body = new Class({
         this.allowGravity = true;
 
         /**
-         * [description]
+         * Acceleration due to gravity (specific to this Body), in pixels per second squared.
+         * Total gravity is the sum of this vector and the simulation's `gravity`.
          *
          * @name Phaser.Physics.Arcade.Body#gravity
          * @type {Phaser.Math.Vector2}
@@ -344,7 +356,7 @@ var Body = new Class({
         this.gravity = new Vector2();
 
         /**
-         * [description]
+         * Rebound following a collision, relative to 1.
          *
          * @name Phaser.Physics.Arcade.Body#bounce
          * @type {Phaser.Math.Vector2}
@@ -353,7 +365,8 @@ var Body = new Class({
         this.bounce = new Vector2();
 
         /**
-         * [description]
+         * Rebound following a collision with the world boundary, relative to 1.
+         * If empty, `bounce` is used instead.
          *
          * @name Phaser.Physics.Arcade.Body#worldBounce
          * @type {?Phaser.Math.Vector2}
@@ -365,37 +378,41 @@ var Body = new Class({
         //  If true this Body will dispatch events
 
         /**
-         * Emit a `worldbounds` event when this body collides with the world bounds (and `collideWorldBounds` is also true).
+         * Whether the simulation emits a `worldbounds` event when this Body collides with the world boundary (and `collideWorldBounds` is also true).
          *
          * @name Phaser.Physics.Arcade.Body#onWorldBounds
          * @type {boolean}
          * @default false
          * @since 3.0.0
+         * @see Phaser.Physics.Arcade.World#event:worldbounds
          */
         this.onWorldBounds = false;
 
         /**
-         * [description]
+         * Whether the simulation emits a `collide` event when this Body collides with another.
          *
          * @name Phaser.Physics.Arcade.Body#onCollide
          * @type {boolean}
          * @default false
          * @since 3.0.0
+         * @see Phaser.Physics.Arcade.World#event:collide
          */
         this.onCollide = false;
 
         /**
-         * [description]
+         * Whether the simulation emits an `overlap` event when this Body overlaps with another.
          *
          * @name Phaser.Physics.Arcade.Body#onOverlap
          * @type {boolean}
          * @default false
          * @since 3.0.0
+         * @see Phaser.Physics.Arcade.World#event:overlap
          */
         this.onOverlap = false;
 
         /**
-         * [description]
+         * The Body's absolute maximum velocity, in pixels per second.
+         * This limits the Body's rate of movement but not its `velocity` values (which can still exceed `maxVelocity`).
          *
          * @name Phaser.Physics.Arcade.Body#maxVelocity
          * @type {Phaser.Math.Vector2}
@@ -404,7 +421,8 @@ var Body = new Class({
         this.maxVelocity = new Vector2(10000, 10000);
 
         /**
-         * [description]
+         * If this Body is `immovable` and in motion, this the proportion of this Body's movement received by the riding body on each axis, relative to 1.
+         * The default value (1, 0) moves the riding body horizontally in equal proportion and vertically not at all.
          *
          * @name Phaser.Physics.Arcade.Body#friction
          * @type {Phaser.Math.Vector2}
@@ -413,7 +431,7 @@ var Body = new Class({
         this.friction = new Vector2(1, 0);
 
         /**
-         * [description]
+         * The rate of change of this Body's rotation, in degrees per second.
          *
          * @name Phaser.Physics.Arcade.Body#angularVelocity
          * @type {number}
@@ -423,7 +441,7 @@ var Body = new Class({
         this.angularVelocity = 0;
 
         /**
-         * [description]
+         * The rate of change of this Body's angular velocity, in degrees per second squared.
          *
          * @name Phaser.Physics.Arcade.Body#angularAcceleration
          * @type {number}
@@ -433,7 +451,7 @@ var Body = new Class({
         this.angularAcceleration = 0;
 
         /**
-         * [description]
+         * Loss of angular velocity due to angular movement, in degrees per second.
          *
          * @name Phaser.Physics.Arcade.Body#angularDrag
          * @type {number}
@@ -443,7 +461,7 @@ var Body = new Class({
         this.angularDrag = 0;
 
         /**
-         * [description]
+         * The Body's maximum angular velocity, in degrees per second.
          *
          * @name Phaser.Physics.Arcade.Body#maxAngular
          * @type {number}
@@ -453,7 +471,8 @@ var Body = new Class({
         this.maxAngular = 1000;
 
         /**
-         * [description]
+         * The Body's inertia, relative to a default unit (1).
+         * With `bounce`, this affects the exchange of momentum (velocities) during collisions.
          *
          * @name Phaser.Physics.Arcade.Body#mass
          * @type {number}
@@ -463,7 +482,7 @@ var Body = new Class({
         this.mass = 1;
 
         /**
-         * [description]
+         * The angle of this Body's velocity vector, in degrees.
          *
          * @name Phaser.Physics.Arcade.Body#angle
          * @type {number}
@@ -473,7 +492,7 @@ var Body = new Class({
         this.angle = 0;
 
         /**
-         * [description]
+         * The magnitude of the Body's velocity, as calculated during the last update.
          *
          * @name Phaser.Physics.Arcade.Body#speed
          * @type {number}
@@ -483,7 +502,7 @@ var Body = new Class({
         this.speed = 0;
 
         /**
-         * [description]
+         * The calculated direction of the Body's velocity.
          *
          * @name Phaser.Physics.Arcade.Body#facing
          * @type {integer}
@@ -492,7 +511,7 @@ var Body = new Class({
         this.facing = CONST.FACING_NONE;
 
         /**
-         * [description]
+         * Whether this object can be moved by collisions with another body.
          *
          * @name Phaser.Physics.Arcade.Body#immovable
          * @type {boolean}
@@ -502,7 +521,7 @@ var Body = new Class({
         this.immovable = false;
 
         /**
-         * [description]
+         * Whether the Body's position and rotation are affected by its velocity, acceleration, drag, and gravity.
          *
          * @name Phaser.Physics.Arcade.Body#moves
          * @type {boolean}
@@ -512,7 +531,7 @@ var Body = new Class({
         this.moves = true;
 
         /**
-         * [description]
+         * A flag disabling the default horizontal separation of colliding bodies. Pass your own `processHandler` to the collider.
          *
          * @name Phaser.Physics.Arcade.Body#customSeparateX
          * @type {boolean}
@@ -522,7 +541,7 @@ var Body = new Class({
         this.customSeparateX = false;
 
         /**
-         * [description]
+         * A flag disabling the default vertical separation of colliding bodies. Pass your own `processHandler` to the collider.
          *
          * @name Phaser.Physics.Arcade.Body#customSeparateY
          * @type {boolean}
@@ -532,7 +551,7 @@ var Body = new Class({
         this.customSeparateY = false;
 
         /**
-         * [description]
+         * The amount of horizontal overlap (before separation), if this Body is colliding with another.
          *
          * @name Phaser.Physics.Arcade.Body#overlapX
          * @type {number}
@@ -542,7 +561,7 @@ var Body = new Class({
         this.overlapX = 0;
 
         /**
-         * [description]
+         * The amount of vertical overlap (before separation), if this Body is colliding with another.
          *
          * @name Phaser.Physics.Arcade.Body#overlapY
          * @type {number}
@@ -552,7 +571,7 @@ var Body = new Class({
         this.overlapY = 0;
 
         /**
-         * [description]
+         * The amount of overlap (before separation), if this Body is circular and colliding with another circular body.
          *
          * @name Phaser.Physics.Arcade.Body#overlapR
          * @type {number}
@@ -562,7 +581,7 @@ var Body = new Class({
         this.overlapR = 0;
 
         /**
-         * [description]
+         * Whether this Body is overlapped with another and both have zero velocity.
          *
          * @name Phaser.Physics.Arcade.Body#embedded
          * @type {boolean}
@@ -572,7 +591,7 @@ var Body = new Class({
         this.embedded = false;
 
         /**
-         * [description]
+         * Whether this Body interacts with the world boundary.
          *
          * @name Phaser.Physics.Arcade.Body#collideWorldBounds
          * @type {boolean}
@@ -582,7 +601,8 @@ var Body = new Class({
         this.collideWorldBounds = false;
 
         /**
-         * [description]
+         * Whether this Body is checked for collisions and for which directions.
+         * You can set `checkCollision.none = false` to disable collision checks.
          *
          * @name Phaser.Physics.Arcade.Body#checkCollision
          * @type {ArcadeBodyCollision}
@@ -591,7 +611,7 @@ var Body = new Class({
         this.checkCollision = { none: false, up: true, down: true, left: true, right: true };
 
         /**
-         * [description]
+         * Whether this Body is colliding with another and in which direction.
          *
          * @name Phaser.Physics.Arcade.Body#touching
          * @type {ArcadeBodyCollision}
@@ -600,7 +620,7 @@ var Body = new Class({
         this.touching = { none: true, up: false, down: false, left: false, right: false };
 
         /**
-         * [description]
+         * Whether this Body was colliding with another during the last step, and in which direction.
          *
          * @name Phaser.Physics.Arcade.Body#wasTouching
          * @type {ArcadeBodyCollision}
@@ -609,7 +629,7 @@ var Body = new Class({
         this.wasTouching = { none: true, up: false, down: false, left: false, right: false };
 
         /**
-         * [description]
+         * Whether this Body is colliding with a tile or the world boundary.
          *
          * @name Phaser.Physics.Arcade.Body#blocked
          * @type {ArcadeBodyCollision}
@@ -618,7 +638,7 @@ var Body = new Class({
         this.blocked = { none: true, up: false, down: false, left: false, right: false };
 
         /**
-         * [description]
+         * Whether this Body is in its `update` phase.
          *
          * @name Phaser.Physics.Arcade.Body#dirty
          * @type {boolean}
@@ -628,17 +648,18 @@ var Body = new Class({
         this.dirty = false;
 
         /**
-         * [description]
+         * Whether to automatically synchronize this Body's dimensions to the dimensions of its Game Object's visual bounds.
          *
          * @name Phaser.Physics.Arcade.Body#syncBounds
          * @type {boolean}
          * @default false
          * @since 3.0.0
+         * @see Phaser.GameObjects.Components.GetBounds#getBounds
          */
         this.syncBounds = false;
 
         /**
-         * [description]
+         * Whether this Body is being moved by the `moveTo` or `moveFrom` methods.
          *
          * @name Phaser.Physics.Arcade.Body#isMoving
          * @type {boolean}
@@ -648,7 +669,7 @@ var Body = new Class({
         this.isMoving = false;
 
         /**
-         * [description]
+         * Whether this Body's movement by `moveTo` or `moveFrom` will be stopped by collisions with other bodies.
          *
          * @name Phaser.Physics.Arcade.Body#stopVelocityOnCollide
          * @type {boolean}
@@ -660,7 +681,7 @@ var Body = new Class({
         //  read-only
 
         /**
-         * [description]
+         * The Body's physics type (dynamic or static).
          *
          * @name Phaser.Physics.Arcade.Body#physicsType
          * @type {integer}
@@ -670,7 +691,7 @@ var Body = new Class({
         this.physicsType = CONST.DYNAMIC_BODY;
 
         /**
-         * [description]
+         * Whether the Body's position needs updating from its Game Object.
          *
          * @name Phaser.Physics.Arcade.Body#_reset
          * @type {boolean}
@@ -681,7 +702,7 @@ var Body = new Class({
         this._reset = true;
 
         /**
-         * [description]
+         * Cached horizontal scale of the Body's Game Object.
          *
          * @name Phaser.Physics.Arcade.Body#_sx
          * @type {number}
@@ -691,7 +712,7 @@ var Body = new Class({
         this._sx = gameObject.scaleX;
 
         /**
-         * [description]
+         * Cached vertical scale of the Body's Game Object.
          *
          * @name Phaser.Physics.Arcade.Body#_sy
          * @type {number}
@@ -701,7 +722,7 @@ var Body = new Class({
         this._sy = gameObject.scaleY;
 
         /**
-         * [description]
+         * The calculated change in the Body's horizontal position during the current step.
          *
          * @name Phaser.Physics.Arcade.Body#_dx
          * @type {number}
@@ -712,7 +733,7 @@ var Body = new Class({
         this._dx = 0;
 
         /**
-         * [description]
+         * The calculated change in the Body's vertical position during the current step.
          *
          * @name Phaser.Physics.Arcade.Body#_dy
          * @type {number}
@@ -723,7 +744,7 @@ var Body = new Class({
         this._dy = 0;
 
         /**
-         * [description]
+         * Stores the Game Object's bounds.
          *
          * @name Phaser.Physics.Arcade.Body#_bounds
          * @type {Phaser.Geom.Rectangle}
@@ -736,7 +757,7 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Updates this Body's transform, dimensions, and position from its Game Object.
      *
      * @method Phaser.Physics.Arcade.Body#updateBounds
      * @since 3.0.0
@@ -803,7 +824,7 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Updates the Body's `center` from its `position` and dimensions.
      *
      * @method Phaser.Physics.Arcade.Body#updateCenter
      * @since 3.0.0
@@ -814,12 +835,13 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Updates the Body.
      *
      * @method Phaser.Physics.Arcade.Body#update
+     * @fires Phaser.Physics.Arcade.World#worldbounds
      * @since 3.0.0
      *
-     * @param {number} delta - [description]
+     * @param {number} delta - The delta time, in ms, elapsed since the last frame.
      */
     update: function (delta)
     {
@@ -904,7 +926,7 @@ var Body = new Class({
     },
 
     /**
-     * Feeds the body results back into the parent gameobject.
+     * Feeds the Body results back into the parent Game Object.
      *
      * @method Phaser.Physics.Arcade.Body#postUpdate
      * @since 3.0.0
@@ -987,12 +1009,12 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Checks for collisions between this Body and the world boundary and separates them.
      *
      * @method Phaser.Physics.Arcade.Body#checkWorldBounds
      * @since 3.0.0
      *
-     * @return {boolean} [description]
+     * @return {boolean} True if this Body is colliding with the world boundary.
      */
     checkWorldBounds: function ()
     {
@@ -1037,13 +1059,13 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the offset of the Body's position from its Game Object's position.
      *
      * @method Phaser.Physics.Arcade.Body#setOffset
      * @since 3.0.0
      *
-     * @param {number} x - [description]
-     * @param {number} y - [description]
+     * @param {number} x - The horizontal offset, in source pixels.
+     * @param {number} [y=x] - The vertical offset, in source pixels.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1057,14 +1079,15 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sizes and positions this Body's boundary, as a rectangle.
+     * Modifies the Body's `offset` if `center` is true (the default).
      *
      * @method Phaser.Physics.Arcade.Body#setSize
      * @since 3.0.0
      *
-     * @param {number} width - [description]
-     * @param {number} height - [description]
-     * @param {boolean} [center=true] - [description]
+     * @param {number} width - The width of the Body, in source pixels.
+     * @param {number} height - The height of the Body, in source pixels.
+     * @param {boolean} [center=true] - Modify the Body's `offset`, placing the Body's center on its Game Object's center.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1100,14 +1123,14 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sizes and positions this Body's boundary, as a circle.
      *
      * @method Phaser.Physics.Arcade.Body#setCircle
      * @since 3.0.0
      *
-     * @param {number} radius - [description]
-     * @param {number} [offsetX] - [description]
-     * @param {number} [offsetY] - [description]
+     * @param {number} radius - The radius of the Body, in source pixels.
+     * @param {number} [offsetX] - The horizontal offset of the Body from its Game Object, in source pixels.
+     * @param {number} [offsetY] - The vertical offset of the Body from its Game Object, in source pixels.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1144,7 +1167,7 @@ var Body = new Class({
 
     /**
      * Resets this Body to the given coordinates. Also positions its parent Game Object to the same coordinates.
-     * If the body had any velocity or acceleration it is lost as a result of calling this.
+     * If the Body had any velocity or acceleration it is lost as a result of calling this.
      *
      * @method Phaser.Physics.Arcade.Body#reset
      * @since 3.0.0
@@ -1172,7 +1195,7 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets acceleration, velocity, and speed to zero.
      *
      * @method Phaser.Physics.Arcade.Body#stop
      * @since 3.0.0
@@ -1191,14 +1214,14 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Copies the coordinates of this Body's edges into an object.
      *
      * @method Phaser.Physics.Arcade.Body#getBounds
      * @since 3.0.0
      *
-     * @param {ArcadeBodyBounds} obj - [description]
+     * @param {ArcadeBodyBounds} obj - An object to copy the values into.
      *
-     * @return {ArcadeBodyBounds} [description]
+     * @return {ArcadeBodyBounds} - An object with {x, y, right, bottom}.
      */
     getBounds: function (obj)
     {
@@ -1211,15 +1234,15 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Tests if the coordinates are within this Body's boundary.
      *
      * @method Phaser.Physics.Arcade.Body#hitTest
      * @since 3.0.0
      *
-     * @param {number} x - [description]
-     * @param {number} y - [description]
+     * @param {number} x - The horizontal coordinate.
+     * @param {number} y - The vertical coordinate.
      *
-     * @return {boolean} [description]
+     * @return {boolean} True if (x, y) is within this Body.
      */
     hitTest: function (x, y)
     {
@@ -1227,12 +1250,13 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Whether this Body is touching a tile or the world boundary while moving down.
      *
      * @method Phaser.Physics.Arcade.Body#onFloor
      * @since 3.0.0
+     * @see Phaser.Physics.Arcade.Body#blocked
      *
-     * @return {boolean} [description]
+     * @return {boolean} True if touching.
      */
     onFloor: function ()
     {
@@ -1240,12 +1264,13 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Whether this Body is touching a tile or the world boundary while moving up.
      *
      * @method Phaser.Physics.Arcade.Body#onCeiling
      * @since 3.0.0
+     * @see Phaser.Physics.Arcade.Body#blocked
      *
-     * @return {boolean} [description]
+     * @return {boolean} True if touching.
      */
     onCeiling: function ()
     {
@@ -1253,12 +1278,13 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Whether this Body is touching a tile or the world boundary while moving left or right.
      *
      * @method Phaser.Physics.Arcade.Body#onWall
      * @since 3.0.0
+     * @see Phaser.Physics.Arcade.Body#blocked
      *
-     * @return {boolean} [description]
+     * @return {boolean} True if touching.
      */
     onWall: function ()
     {
@@ -1266,12 +1292,13 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * The absolute (nonnegative) change in this Body's horizontal position from the previous step.
+     * This value is set only during the Body's `dirty` (update) phase.
      *
      * @method Phaser.Physics.Arcade.Body#deltaAbsX
      * @since 3.0.0
      *
-     * @return {number} [description]
+     * @return {number} The delta value.
      */
     deltaAbsX: function ()
     {
@@ -1279,12 +1306,13 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * The absolute (nonnegative) change in this Body's horizontal position from the previous step.
+     * This value is set only during the Body's `dirty` (update) phase.
      *
      * @method Phaser.Physics.Arcade.Body#deltaAbsY
      * @since 3.0.0
      *
-     * @return {number} [description]
+     * @return {number} The delta value.
      */
     deltaAbsY: function ()
     {
@@ -1292,12 +1320,13 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * The change in this Body's horizontal position from the previous step.
+     * This value is set only during the Body's `dirty` (update) phase.
      *
      * @method Phaser.Physics.Arcade.Body#deltaX
      * @since 3.0.0
      *
-     * @return {number} [description]
+     * @return {number} The delta value.
      */
     deltaX: function ()
     {
@@ -1305,12 +1334,12 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * The change in this Body's vertical position from the previous step.
      *
      * @method Phaser.Physics.Arcade.Body#deltaY
      * @since 3.0.0
      *
-     * @return {number} [description]
+     * @return {number} The delta value.
      */
     deltaY: function ()
     {
@@ -1318,12 +1347,12 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * The change in this Body's rotation from the previous step, in degrees.
      *
      * @method Phaser.Physics.Arcade.Body#deltaZ
      * @since 3.0.0
      *
-     * @return {number} [description]
+     * @return {number} The delta value.
      */
     deltaZ: function ()
     {
@@ -1331,7 +1360,7 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Disables this Body and marks it for deletion by the simulation.
      *
      * @method Phaser.Physics.Arcade.Body#destroy
      * @since 3.0.0
@@ -1344,12 +1373,12 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Draws this Body's boundary and velocity, if enabled.
      *
      * @method Phaser.Physics.Arcade.Body#drawDebug
      * @since 3.0.0
      *
-     * @param {Phaser.GameObjects.Graphics} graphic - [description]
+     * @param {Phaser.GameObjects.Graphics} graphic - The Graphics object to draw on.
      */
     drawDebug: function (graphic)
     {
@@ -1379,12 +1408,12 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Whether this Body will be drawn to the debug display.
      *
      * @method Phaser.Physics.Arcade.Body#willDrawDebug
      * @since 3.0.0
      *
-     * @return {boolean} [description]
+     * @return {boolean} True if either `debugShowBody` or `debugShowVelocity` are enabled.
      */
     willDrawDebug: function ()
     {
@@ -1392,12 +1421,12 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets whether this Body collides with the world boundary.
      *
      * @method Phaser.Physics.Arcade.Body#setCollideWorldBounds
      * @since 3.0.0
      *
-     * @param {boolean} value - [description]
+     * @param {boolean} value - True (collisions) or false (no collisions).
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1409,13 +1438,13 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the Body's velocity.
      *
      * @method Phaser.Physics.Arcade.Body#setVelocity
      * @since 3.0.0
      *
-     * @param {number} x - [description]
-     * @param {number} y - [description]
+     * @param {number} x - The horizontal velocity, in pixels per second.
+     * @param {number} y - The vertical velocity, in pixels per second.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1427,12 +1456,12 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the Body's horizontal velocity.
      *
      * @method Phaser.Physics.Arcade.Body#setVelocityX
      * @since 3.0.0
      *
-     * @param {number} value - [description]
+     * @param {number} value - The velocity, in pixels per second.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1444,12 +1473,12 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the Body's vertical velocity.
      *
      * @method Phaser.Physics.Arcade.Body#setVelocityY
      * @since 3.0.0
      *
-     * @param {number} value - [description]
+     * @param {number} value - The velocity, in pixels per second.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1461,13 +1490,13 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the Body's bounce.
      *
      * @method Phaser.Physics.Arcade.Body#setBounce
      * @since 3.0.0
      *
-     * @param {number} x - [description]
-     * @param {number} y - [description]
+     * @param {number} x - The horizontal bounce, relative to 1.
+     * @param {number} y - The vertical bounce, relative to 1.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1479,12 +1508,12 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the Body's horizontal bounce.
      *
      * @method Phaser.Physics.Arcade.Body#setBounceX
      * @since 3.0.0
      *
-     * @param {number} value - [description]
+     * @param {number} value - The bounce, relative to 1.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1496,12 +1525,12 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the Body's vertical bounce.
      *
      * @method Phaser.Physics.Arcade.Body#setBounceY
      * @since 3.0.0
      *
-     * @param {number} value - [description]
+     * @param {number} value - The bounce, relative to 1.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1513,13 +1542,13 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the Body's acceleration.
      *
      * @method Phaser.Physics.Arcade.Body#setAcceleration
      * @since 3.0.0
      *
-     * @param {number} x - [description]
-     * @param {number} y - [description]
+     * @param {number} x - The horizontal component, in pixels per second squared.
+     * @param {number} y - The vertical component, in pixels per second squared.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1531,12 +1560,12 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the Body's horizontal acceleration.
      *
      * @method Phaser.Physics.Arcade.Body#setAccelerationX
      * @since 3.0.0
      *
-     * @param {number} value - [description]
+     * @param {number} value - The acceleration, in pixels per second squared.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1548,12 +1577,12 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the Body's vertical acceleration.
      *
      * @method Phaser.Physics.Arcade.Body#setAccelerationY
      * @since 3.0.0
      *
-     * @param {number} value - [description]
+     * @param {number} value - The acceleration, in pixels per second squared.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1565,13 +1594,13 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the Body's drag.
      *
      * @method Phaser.Physics.Arcade.Body#setDrag
      * @since 3.0.0
      *
-     * @param {number} x - [description]
-     * @param {number} y - [description]
+     * @param {number} x - The horizontal component, in pixels per second squared.
+     * @param {number} y - The vertical component, in pixels per second squared.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1583,12 +1612,12 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the Body's horizontal drag.
      *
      * @method Phaser.Physics.Arcade.Body#setDragX
      * @since 3.0.0
      *
-     * @param {number} value - [description]
+     * @param {number} value - The drag, in pixels per second squared.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1600,12 +1629,12 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the Body's vertical drag.
      *
      * @method Phaser.Physics.Arcade.Body#setDragY
      * @since 3.0.0
      *
-     * @param {number} value - [description]
+     * @param {number} value - The drag, in pixels per second squared.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1617,13 +1646,13 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the Body's gravity.
      *
      * @method Phaser.Physics.Arcade.Body#setGravity
      * @since 3.0.0
      *
-     * @param {number} x - [description]
-     * @param {number} y - [description]
+     * @param {number} x - The horizontal component, in pixels per second squared.
+     * @param {number} y - The vertical component, in pixels per second squared.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1635,12 +1664,12 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the Body's horizontal gravity.
      *
      * @method Phaser.Physics.Arcade.Body#setGravityX
      * @since 3.0.0
      *
-     * @param {number} value - [description]
+     * @param {number} value - The gravity, in pixels per second squared.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1652,12 +1681,12 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the Body's vertical gravity.
      *
      * @method Phaser.Physics.Arcade.Body#setGravityY
      * @since 3.0.0
      *
-     * @param {number} value - [description]
+     * @param {number} value - The gravity, in pixels per second squared.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1669,13 +1698,13 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the Body's friction.
      *
      * @method Phaser.Physics.Arcade.Body#setFriction
      * @since 3.0.0
      *
-     * @param {number} x - [description]
-     * @param {number} y - [description]
+     * @param {number} x - The horizontal component, relative to 1.
+     * @param {number} y - The vertical component, relative to 1.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1687,12 +1716,12 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the Body's horizontal friction.
      *
      * @method Phaser.Physics.Arcade.Body#setFrictionX
      * @since 3.0.0
      *
-     * @param {number} value - [description]
+     * @param {number} value - The friction value, relative to 1.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1704,12 +1733,12 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the Body's vertical friction.
      *
      * @method Phaser.Physics.Arcade.Body#setFrictionY
      * @since 3.0.0
      *
-     * @param {number} value - [description]
+     * @param {number} value - The friction value, relative to 1.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1721,12 +1750,12 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the Body's angular velocity.
      *
      * @method Phaser.Physics.Arcade.Body#setAngularVelocity
      * @since 3.0.0
      *
-     * @param {number} value - [description]
+     * @param {number} value - The velocity, in degrees per second.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1738,12 +1767,12 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the Body's angular acceleration.
      *
      * @method Phaser.Physics.Arcade.Body#setAngularAcceleration
      * @since 3.0.0
      *
-     * @param {number} value - [description]
+     * @param {number} value - The acceleration, in degrees per second squared.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1755,12 +1784,12 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the Body's angular drag.
      *
      * @method Phaser.Physics.Arcade.Body#setAngularDrag
      * @since 3.0.0
      *
-     * @param {number} value - [description]
+     * @param {number} value - The drag, in degrees per second squared.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1772,12 +1801,12 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the Body's mass.
      *
      * @method Phaser.Physics.Arcade.Body#setMass
      * @since 3.0.0
      *
-     * @param {number} value - [description]
+     * @param {number} value - The mass value, relative to 1.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1789,12 +1818,12 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * Sets the Body's `immovable` property.
      *
      * @method Phaser.Physics.Arcade.Body#setImmovable
      * @since 3.0.0
      *
-     * @param {boolean} value - [description]
+     * @param {boolean} value - The value to assign to `immovable`.
      *
      * @return {Phaser.Physics.Arcade.Body} This Body object.
      */
@@ -1806,7 +1835,7 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * The Body's horizontal position (left edge).
      *
      * @name Phaser.Physics.Arcade.Body#x
      * @type {number}
@@ -1827,7 +1856,7 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * The Body's vertical position (top edge).
      *
      * @name Phaser.Physics.Arcade.Body#y
      * @type {number}
@@ -1848,7 +1877,7 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * The left edge of the Body's boundary. Identical to x.
      *
      * @name Phaser.Physics.Arcade.Body#left
      * @type {number}
@@ -1865,7 +1894,7 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * The right edge of the Body's boundary.
      *
      * @name Phaser.Physics.Arcade.Body#right
      * @type {number}
@@ -1882,7 +1911,7 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * The top edge of the Body's boundary. Identical to y.
      *
      * @name Phaser.Physics.Arcade.Body#top
      * @type {number}
@@ -1899,7 +1928,7 @@ var Body = new Class({
     },
 
     /**
-     * [description]
+     * The bottom edge of this Body's boundary.
      *
      * @name Phaser.Physics.Arcade.Body#bottom
      * @type {number}
diff --git a/src/physics/arcade/PhysicsGroup.js b/src/physics/arcade/PhysicsGroup.js
index a01dbf633..70fdac93f 100644
--- a/src/physics/arcade/PhysicsGroup.js
+++ b/src/physics/arcade/PhysicsGroup.js
@@ -14,30 +14,30 @@ var Group = require('../../gameobjects/group/Group');
  * @typedef {object} PhysicsGroupConfig
  * @extends GroupConfig
  *
- * @property {[type]} [collideWorldBounds=false] - [description]
- * @property {number} [accelerationX=0] - [description]
- * @property {number} [accelerationY=0] - [description]
- * @property {number} [bounceX=0] - [description]
- * @property {number} [bounceY=0] - [description]
- * @property {number} [dragX=0] - [description]
- * @property {number} [dragY=0] - [description]
- * @property {number} [gravityX=0] - [description]
- * @property {number} [gravityY=0] - [description]
- * @property {number} [frictionX=0] - [description]
- * @property {number} [frictionY=0] - [description]
- * @property {number} [velocityX=0] - [description]
- * @property {number} [velocityY=0] - [description]
- * @property {number} [angularVelocity=0] - [description]
- * @property {number} [angularAcceleration=0] - [description]
- * @property {number} [angularDrag=0] - [description]
- * @property {number} [mass=0] - [description]
- * @property {boolean} [immovable=false] - [description]
+ * @property {boolean} [collideWorldBounds=false] - Sets {@link Phaser.Physics.Arcade.Body#collideWorldBounds}.
+ * @property {number} [accelerationX=0] - Sets {@link Phaser.Physics.Arcade.Body#acceleration acceleration.x}.
+ * @property {number} [accelerationY=0] - Sets {@link Phaser.Physics.Arcade.Body#acceleration acceleration.y}.
+ * @property {number} [bounceX=0] - Sets {@link Phaser.Physics.Arcade.Body#bounce bounce.x}.
+ * @property {number} [bounceY=0] - Sets {@link Phaser.Physics.Arcade.Body#bounce bounce.y}.
+ * @property {number} [dragX=0] - Sets {@link Phaser.Physics.Arcade.Body#drag drag.x}.
+ * @property {number} [dragY=0] - Sets {@link Phaser.Physics.Arcade.Body#drag drag.y}.
+ * @property {number} [gravityX=0] - Sets {@link Phaser.Physics.Arcade.Body#gravity gravity.x}.
+ * @property {number} [gravityY=0] - Sets {@link Phaser.Physics.Arcade.Body#gravity gravity.y}.
+ * @property {number} [frictionX=0] - Sets {@link Phaser.Physics.Arcade.Body#friction friction.x}.
+ * @property {number} [frictionY=0] - Sets {@link Phaser.Physics.Arcade.Body#friction friction.y}.
+ * @property {number} [velocityX=0] - Sets {@link Phaser.Physics.Arcade.Body#velocity velocity.x}.
+ * @property {number} [velocityY=0] - Sets {@link Phaser.Physics.Arcade.Body#velocity velocity.y}.
+ * @property {number} [angularVelocity=0] - Sets {@link Phaser.Physics.Arcade.Body#angularVelocity}.
+ * @property {number} [angularAcceleration=0] - Sets {@link Phaser.Physics.Arcade.Body#angularAcceleration}.
+ * @property {number} [angularDrag=0] - Sets {@link Phaser.Physics.Arcade.Body#angularDrag}.
+ * @property {number} [mass=0] - Sets {@link Phaser.Physics.Arcade.Body#mass}.
+ * @property {boolean} [immovable=false] - Sets {@link Phaser.Physics.Arcade.Body#immovable}.
  */
 
 /**
  * @typedef {object} PhysicsGroupDefaults
  *
- * @property {[type]} setCollideWorldBounds - [description]
+ * @property {boolean} setCollideWorldBounds - [description]
  * @property {number} setAccelerationX - [description]
  * @property {number} setAccelerationY - [description]
  * @property {number} setBounceX - [description]
@@ -104,6 +104,13 @@ var PhysicsGroup = new Class({
         config.createCallback = this.createCallbackHandler;
         config.removeCallback = this.removeCallbackHandler;
 
+        /**
+         * The class to create new group members from.
+         *
+         * @name Phaser.Physics.Arcade.Group#classType
+         * @type {Phaser.Physics.Arcade.Sprite}
+         * @default ArcadeSprite
+         */
         config.classType = GetFastValue(config, 'classType', ArcadeSprite);
 
         /**
diff --git a/src/physics/arcade/World.js b/src/physics/arcade/World.js
index 1c674090e..25ad6e835 100644
--- a/src/physics/arcade/World.js
+++ b/src/physics/arcade/World.js
@@ -27,33 +27,66 @@ var TileIntersectsBody = require('./tilemap/TileIntersectsBody');
 var Vector2 = require('../../math/Vector2');
 var Wrap = require('../../math/Wrap');
 
+/**
+ * @event Phaser.Physics.Arcade.World#pause
+ */
+
+/**
+ * @event Phaser.Physics.Arcade.World#resume
+ */
+
+/**
+ * @event Phaser.Physics.Arcade.World#collide
+ * @param {Phaser.GameObjects.GameObject} gameObject1
+ * @param {Phaser.GameObjects.GameObject} gameObject2
+ * @param {Phaser.Physics.Arcade.Body|Phaser.Physics.Arcade.StaticBody} body1
+ * @param {Phaser.Physics.Arcade.Body|Phaser.Physics.Arcade.StaticBody} body2
+ */
+
+/**
+ * @event Phaser.Physics.Arcade.World#overlap
+ * @param {Phaser.GameObjects.GameObject} gameObject1
+ * @param {Phaser.GameObjects.GameObject} gameObject2
+ * @param {Phaser.Physics.Arcade.Body|Phaser.Physics.Arcade.StaticBody} body1
+ * @param {Phaser.Physics.Arcade.Body|Phaser.Physics.Arcade.StaticBody} body2
+ */
+
+/**
+ * @event Phaser.Physics.Arcade.World#worldbounds
+ * @param {Phaser.Physics.Arcade.Body} body
+ * @param {boolean} up
+ * @param {boolean} down
+ * @param {boolean} left
+ * @param {boolean} right
+ */
+
 /**
  * @typedef {object} ArcadeWorldConfig
  *
- * @property {object} [gravity] - [description]
+ * @property {object} [gravity] - Sets {@link Phaser.Physics.Arcade.World#gravity}.
  * @property {number} [gravity.x=0] - [description]
  * @property {number} [gravity.y=0] - [description]
- * @property {number} [x=0] - [description]
- * @property {number} [y=0] - [description]
- * @property {number} [width=0] - [description]
- * @property {number} [height=0] - [description]
- * @property {object} [checkCollision] - [description]
+ * @property {number} [x=0] - Sets {@link Phaser.Physics.Arcade.World#bounds bounds.x}.
+ * @property {number} [y=0] - Sets {@link Phaser.Physics.Arcade.World#bounds bounds.y}.
+ * @property {number} [width=0] - Sets {@link Phaser.Physics.Arcade.World#bounds bounds.width}.
+ * @property {number} [height=0] - Sets {@link Phaser.Physics.Arcade.World#bounds bounds.height}.
+ * @property {object} [checkCollision] - Sets {@link Phaser.Physics.Arcade.World#checkCollision}.
  * @property {boolean} [checkCollision.up=true] - [description]
  * @property {boolean} [checkCollision.down=true] - [description]
  * @property {boolean} [checkCollision.left=true] - [description]
  * @property {boolean} [checkCollision.right=true] - [description]
- * @property {number} [overlapBias=4] - [description]
- * @property {number} [tileBias=16] - [description]
- * @property {boolean} [forceX=false] - [description]
- * @property {boolean} [isPaused=false] - [description]
- * @property {boolean} [debug=false] - [description]
- * @property {boolean} [debugShowBody=true] - [description]
- * @property {boolean} [debugShowStaticBody=true] - [description]
- * @property {boolean} [debugShowVelocity=true] - [description]
- * @property {number} [debugBodyColor=0xff00ff] - [description]
- * @property {number} [debugStaticBodyColor=0x0000ff] - [description]
- * @property {number} [debugVelocityColor=0x00ff00] - [description]
- * @property {number} [maxEntries=16] - [description]
+ * @property {number} [overlapBias=4] - Sets {@link Phaser.Physics.Arcade.World#OVERLAP_BIAS}.
+ * @property {number} [tileBias=16] - Sets {@link Phaser.Physics.Arcade.World#TILE_BIAS}.
+ * @property {boolean} [forceX=false] - Sets {@link Phaser.Physics.Arcade.World#forceX}.
+ * @property {boolean} [isPaused=false] - Sets {@link Phaser.Physics.Arcade.World#isPaused}.
+ * @property {boolean} [debug=false] - Sets {@link Phaser.Physics.Arcade.World#debug}.
+ * @property {boolean} [debugShowBody=true] - Sets {@link Phaser.Physics.Arcade.World#defaults debugShowBody}.
+ * @property {boolean} [debugShowStaticBody=true] - Sets {@link Phaser.Physics.Arcade.World#defaults debugShowStaticBody}.
+ * @property {boolean} [debugShowVelocity=true] - Sets {@link Phaser.Physics.Arcade.World#defaults debugShowStaticBody}.
+ * @property {number} [debugBodyColor=0xff00ff] - Sets {@link Phaser.Physics.Arcade.World#defaults debugBodyColor}.
+ * @property {number} [debugStaticBodyColor=0x0000ff] - Sets {@link Phaser.Physics.Arcade.World#defaults debugStaticBodyColor}.
+ * @property {number} [debugVelocityColor=0x00ff00] - Sets {@link Phaser.Physics.Arcade.World#defaults debugVelocityColor}.
+ * @property {number} [maxEntries=16] - Sets {@link Phaser.Physics.Arcade.World#maxEntries}.
  */
 
 /**
@@ -109,7 +142,7 @@ var World = new Class({
         EventEmitter.call(this);
 
         /**
-         * [description]
+         * The Scene this simulation belongs to.
          *
          * @name Phaser.Physics.Arcade.World#scene
          * @type {Phaser.Scene}
@@ -118,7 +151,7 @@ var World = new Class({
         this.scene = scene;
 
         /**
-         * Dynamic Bodies
+         * Dynamic Bodies in this simulation.
          *
          * @name Phaser.Physics.Arcade.World#bodies
          * @type {Phaser.Structs.Set.<Phaser.Physics.Arcade.Body>}
@@ -127,7 +160,7 @@ var World = new Class({
         this.bodies = new Set();
 
         /**
-         * Static Bodies
+         * Static Bodies in this simulation.
          *
          * @name Phaser.Physics.Arcade.World#staticBodies
          * @type {Phaser.Structs.Set.<Phaser.Physics.Arcade.StaticBody>}
@@ -136,7 +169,7 @@ var World = new Class({
         this.staticBodies = new Set();
 
         /**
-         * Static Bodies
+         * Static Bodies marked for deletion.
          *
          * @name Phaser.Physics.Arcade.World#pendingDestroy
          * @type {Phaser.Structs.Set.<(Phaser.Physics.Arcade.Body|Phaser.Physics.Arcade.StaticBody)>}
@@ -145,7 +178,7 @@ var World = new Class({
         this.pendingDestroy = new Set();
 
         /**
-         * [description]
+         * This simulation's collision processors.
          *
          * @name Phaser.Physics.Arcade.World#colliders
          * @type {Phaser.Structs.ProcessQueue.<Phaser.Physics.Arcade.Collider>}
@@ -154,7 +187,7 @@ var World = new Class({
         this.colliders = new ProcessQueue();
 
         /**
-         * [description]
+         * Acceleration of Bodies due to gravity, in pixels per second.
          *
          * @name Phaser.Physics.Arcade.World#gravity
          * @type {Phaser.Math.Vector2}
@@ -163,7 +196,7 @@ var World = new Class({
         this.gravity = new Vector2(GetValue(config, 'gravity.x', 0), GetValue(config, 'gravity.y', 0));
 
         /**
-         * [description]
+         * A boundary constraining Bodies.
          *
          * @name Phaser.Physics.Arcade.World#bounds
          * @type {Phaser.Geom.Rectangle}
@@ -177,7 +210,7 @@ var World = new Class({
         );
 
         /**
-         * [description]
+         * The boundary edges that Bodies can collide with.
          *
          * @name Phaser.Physics.Arcade.World#checkCollision
          * @type {CheckCollisionObject}
@@ -191,7 +224,9 @@ var World = new Class({
         };
 
         /**
-         * [description]
+         * The maximum absolute difference of a Body's per-step velocity and its overlap with another Body that will result in separation on *each axis*.
+         * Larger values favor separation.
+         * Smaller values favor no separation.
          *
          * @name Phaser.Physics.Arcade.World#OVERLAP_BIAS
          * @type {number}
@@ -201,7 +236,10 @@ var World = new Class({
         this.OVERLAP_BIAS = GetValue(config, 'overlapBias', 4);
 
         /**
-         * [description]
+         * The maximum absolute value of a Body's overlap with a tile that will result in separation on *each axis*.
+         * Larger values favor separation.
+         * Smaller values favor no separation.
+         * The optimum value may be similar to the tile size.
          *
          * @name Phaser.Physics.Arcade.World#TILE_BIAS
          * @type {number}
@@ -211,7 +249,8 @@ var World = new Class({
         this.TILE_BIAS = GetValue(config, 'tileBias', 16);
 
         /**
-         * [description]
+         * Always separate overlapping Bodies horizontally before vertically.
+         * False (the default) means Bodies are first separated on the axis of greater gravity, or the vertical axis if neither is greater.
          *
          * @name Phaser.Physics.Arcade.World#forceX
          * @type {boolean}
@@ -221,7 +260,7 @@ var World = new Class({
         this.forceX = GetValue(config, 'forceX', false);
 
         /**
-         * [description]
+         * Whether the simulation advances with the game loop.
          *
          * @name Phaser.Physics.Arcade.World#isPaused
          * @type {boolean}
@@ -231,7 +270,7 @@ var World = new Class({
         this.isPaused = GetValue(config, 'isPaused', false);
 
         /**
-         * [description]
+         * Temporary total of colliding Bodies.
          *
          * @name Phaser.Physics.Arcade.World#_total
          * @type {number}
@@ -242,7 +281,7 @@ var World = new Class({
         this._total = 0;
 
         /**
-         * [description]
+         * Enables the debug display.
          *
          * @name Phaser.Physics.Arcade.World#drawDebug
          * @type {boolean}
@@ -252,7 +291,7 @@ var World = new Class({
         this.drawDebug = GetValue(config, 'debug', false);
 
         /**
-         * [description]
+         * The graphics object drawing the debug display.
          *
          * @name Phaser.Physics.Arcade.World#debugGraphic
          * @type {Phaser.GameObjects.Graphics}
@@ -261,7 +300,7 @@ var World = new Class({
         this.debugGraphic;
 
         /**
-         * [description]
+         * Default debug display settings for new Bodies.
          *
          * @name Phaser.Physics.Arcade.World#defaults
          * @type {ArcadeWorldDefaults}
@@ -277,7 +316,7 @@ var World = new Class({
         };
 
         /**
-         * [description]
+         * The maximum number of items per tree node.
          *
          * @name Phaser.Physics.Arcade.World#maxEntries
          * @type {integer}
@@ -287,7 +326,7 @@ var World = new Class({
         this.maxEntries = GetValue(config, 'maxEntries', 16);
 
         /**
-         * [description]
+         * The spatial index of Dynamic Bodies.
          *
          * @name Phaser.Physics.Arcade.World#tree
          * @type {Phaser.Structs.RTree}
@@ -296,7 +335,7 @@ var World = new Class({
         this.tree = new RTree(this.maxEntries);
 
         /**
-         * [description]
+         * The spatial index of Static Bodies.
          *
          * @name Phaser.Physics.Arcade.World#staticTree
          * @type {Phaser.Structs.RTree}
@@ -305,7 +344,7 @@ var World = new Class({
         this.staticTree = new RTree(this.maxEntries);
 
         /**
-         * [description]
+         * Recycled input for tree searches.
          *
          * @name Phaser.Physics.Arcade.World#treeMinMax
          * @type {ArcadeWorldTreeMinMax}
@@ -320,7 +359,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Adds an Arcade Physics Body to a Game Object.
      *
      * @method Phaser.Physics.Arcade.World#enable
      * @since 3.0.0
@@ -363,7 +402,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Helper for Phaser.Physics.Arcade.World#enable.
      *
      * @method Phaser.Physics.Arcade.World#enableBody
      * @since 3.0.0
@@ -397,7 +436,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Remove a Body from the simulation.
      *
      * @method Phaser.Physics.Arcade.World#remove
      * @since 3.0.0
@@ -410,7 +449,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Disables the Body of a Game Object, or the Bodies of several Game Objects.
      *
      * @method Phaser.Physics.Arcade.World#disable
      * @since 3.0.0
@@ -450,7 +489,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Disables the Body of a Game Object.
      *
      * @method Phaser.Physics.Arcade.World#disableGameObjectBody
      * @since 3.1.0
@@ -480,7 +519,8 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Disables a Body.
+     * A disabled Body is ignored by the simulation. It doesn't move or interact with other Bodies.
      *
      * @method Phaser.Physics.Arcade.World#disableBody
      * @since 3.0.0
@@ -504,7 +544,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Creates the graphics object responsible for debug display.
      *
      * @method Phaser.Physics.Arcade.World#createDebugGraphic
      * @since 3.0.0
@@ -525,7 +565,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Sets the dimensions of the world boundary.
      *
      * @method Phaser.Physics.Arcade.World#setBounds
      * @since 3.0.0
@@ -554,7 +594,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Enables or disables collisions on each boundary edge.
      *
      * @method Phaser.Physics.Arcade.World#setBoundsCollision
      * @since 3.0.0
@@ -582,9 +622,10 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Pauses the simulation.
      *
      * @method Phaser.Physics.Arcade.World#pause
+     * @fires Phaser.Physics.Arcade.World#pause
      * @since 3.0.0
      *
      * @return {Phaser.Physics.Arcade.World} This World object.
@@ -599,9 +640,10 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Resumes the simulation, if paused.
      *
      * @method Phaser.Physics.Arcade.World#resume
+     * @fires Phaser.Physics.Arcade.World#resume
      * @since 3.0.0
      *
      * @return {Phaser.Physics.Arcade.World} This World object.
@@ -616,10 +658,11 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Adds a collision processor, which runs automatically.
      *
      * @method Phaser.Physics.Arcade.World#addCollider
      * @since 3.0.0
+     * @see Phaser.Physics.Arcade.World#collide
      *
      * @param {(Phaser.GameObjects.GameObject|Phaser.GameObjects.GameObject[])} object1 - The first object to check for collision.
      * @param {(Phaser.GameObjects.GameObject|Phaser.GameObjects.GameObject[])} object2 - The second object to check for collision.
@@ -643,7 +686,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Adds an overlap processor, which runs automatically.
      *
      * @method Phaser.Physics.Arcade.World#addOverlap
      * @since 3.0.0
@@ -670,7 +713,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Removes a collision or overlap processor.
      *
      * @method Phaser.Physics.Arcade.World#removeCollider
      * @since 3.0.0
@@ -687,13 +730,13 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Advances the simulation.
      *
      * @method Phaser.Physics.Arcade.World#update
      * @since 3.0.0
      *
-     * @param {number} time - [description]
-     * @param {number} delta - [description]
+     * @param {number} time - The current timestamp as generated by the Request Animation Frame or SetTimeout.
+     * @param {number} delta - The delta time, in ms, elapsed since the last frame.
      */
     update: function (time, delta)
     {
@@ -743,7 +786,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Updates bodies, draws the debug display, and handles pending queue operations.
      *
      * @method Phaser.Physics.Arcade.World#postUpdate
      * @since 3.0.0
@@ -832,7 +875,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Calculates a Body's velocity and updates its position.
      *
      * @method Phaser.Physics.Arcade.World#updateMotion
      * @since 3.0.0
@@ -854,7 +897,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Calculates a Body's per-axis velocity.
      *
      * @method Phaser.Physics.Arcade.World#computeVelocity
      * @since 3.0.0
@@ -916,9 +959,11 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Separates two Bodies, when at least one is rectangular.
      *
      * @method Phaser.Physics.Arcade.World#separate
+     * @fires Phaser.Physics.Arcade.World#collide
+     * @fires Phaser.Physics.Arcade.World#overlap
      * @since 3.0.0
      *
      * @param {Phaser.Physics.Arcade.Body} body1 - [description]
@@ -1023,9 +1068,11 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Separates two Bodies, when both are circular.
      *
      * @method Phaser.Physics.Arcade.World#separateCircle
+     * @fires Phaser.Physics.Arcade.World#collide
+     * @fires Phaser.Physics.Arcade.World#overlap
      * @since 3.0.0
      *
      * @param {Phaser.Physics.Arcade.Body} body1 - [description]
@@ -1215,7 +1262,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Tests of two bodies intersect (overlap).
      *
      * @method Phaser.Physics.Arcade.World#intersects
      * @since 3.0.0
@@ -1278,7 +1325,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Tests if a circular Body intersects with another Body.
      *
      * @method Phaser.Physics.Arcade.World#circleBodyIntersects
      * @since 3.0.0
@@ -1300,7 +1347,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Tests if Game Objects overlap.
      *
      * @method Phaser.Physics.Arcade.World#overlap
      * @since 3.0.0
@@ -1311,7 +1358,7 @@ var World = new Class({
      * @param {ArcadePhysicsCallback} [processCallback] - [description]
      * @param {*} [callbackContext] - [description]
      *
-     * @return {boolean} [description]
+     * @return {boolean} True if at least one Game Object overlaps another.
      */
     overlap: function (object1, object2, overlapCallback, processCallback, callbackContext)
     {
@@ -1323,7 +1370,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Tests if Game Objects overlap and separates them (if possible).
      *
      * @method Phaser.Physics.Arcade.World#collide
      * @since 3.0.0
@@ -1334,7 +1381,7 @@ var World = new Class({
      * @param {ArcadePhysicsCallback} [processCallback] - [description]
      * @param {*} [callbackContext] - [description]
      *
-     * @return {boolean} [description]
+     * @return {boolean} True if any overlapping Game Objects were separated.
      */
     collide: function (object1, object2, collideCallback, processCallback, callbackContext)
     {
@@ -1346,7 +1393,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Helper for Phaser.Physics.Arcade.World#collide.
      *
      * @method Phaser.Physics.Arcade.World#collideObjects
      * @since 3.0.0
@@ -1358,7 +1405,7 @@ var World = new Class({
      * @param {*} callbackContext - [description]
      * @param {boolean} overlapOnly - [description]
      *
-     * @return {boolean} [description]
+     * @return {boolean} True if any overlapping objects were separated.
      */
     collideObjects: function (object1, object2, collideCallback, processCallback, callbackContext, overlapOnly)
     {
@@ -1407,7 +1454,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Helper for Phaser.Physics.Arcade.World#collide and Phaser.Physics.Arcade.World#overlap.
      *
      * @method Phaser.Physics.Arcade.World#collideHandler
      * @since 3.0.0
@@ -1485,7 +1532,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Handler for Sprite vs. Sprite collisions.
      *
      * @method Phaser.Physics.Arcade.World#collideSpriteVsSprite
      * @since 3.0.0
@@ -1520,7 +1567,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Handler for Sprite vs. Group collisions.
      *
      * @method Phaser.Physics.Arcade.World#collideSpriteVsGroup
      * @since 3.0.0
@@ -1583,7 +1630,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Helper for Group vs. Tilemap collisions.
      *
      * @method Phaser.Physics.Arcade.World#collideGroupVsTilemapLayer
      * @since 3.0.0
@@ -1623,9 +1670,11 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Helper for Sprite vs. Tilemap collisions.
      *
      * @method Phaser.Physics.Arcade.World#collideSpriteVsTilemapLayer
+     * @fires Phaser.Physics.Arcade.World#collide
+     * @fires Phaser.Physics.Arcade.World#overlap
      * @since 3.0.0
      *
      * @param {Phaser.GameObjects.GameObject} sprite - [description]
@@ -1722,7 +1771,7 @@ var World = new Class({
     },
 
     /**
-     * TODO!
+     * Helper for Group vs. Group collisions.
      *
      * @method Phaser.Physics.Arcade.World#collideGroupVsGroup
      * @since 3.0.0
@@ -1826,7 +1875,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Shuts down the simulation, clearing physics data and removing listeners.
      *
      * @method Phaser.Physics.Arcade.World#shutdown
      * @since 3.0.0
@@ -1843,7 +1892,7 @@ var World = new Class({
     },
 
     /**
-     * [description]
+     * Shuts down the simulation and disconnects it from the current scene.
      *
      * @method Phaser.Physics.Arcade.World#destroy
      * @since 3.0.0