Merge pull request #584 from benhinchley/benhinchley-acceleration-docs

Start to add inline docs for acceleration

Author: Lauren McCarthy

src/input/acceleration.js

@@ -1,19 +1,80 @@
+/**
+ * @module Input
+ * @submodule Acceleration
+ * @for p5
+ * @requires core
+ */
 define(function (require){
 
   'use strict';
 
   var p5 = require('core');
-  
+
+  /**
+   * The system variable deviceOrientation always contains the orientation of
+   * the device. The value of this variable will either be set 'landscape'
+   * or 'portrait'. If no data is avaliable it will be set to 'undefined'.
+   *
+   * @property deviceOrientation
+   */
   p5.prototype.deviceOrientation = undefined;
 
+  /**
+   * The system variable accelerationX always contains the acceleration of the
+   * device along the x axis. Value is represented as meters per second squared.
+   *
+   * @property accelerationX
+   */
   p5.prototype.accelerationX = 0;
+
+  /**
+   * The system variable accelerationY always contains the acceleration of the
+   * device along the y axis. Value is represented as meters per second squared.
+   *
+   * @property accelerationY
+   */
   p5.prototype.accelerationY = 0;
+
+  /**
+   * The system variable accelerationZ always contains the acceleration of the
+   * device along the z axis. Value is represented as meters per second squared.
+   *
+   * @property accelerationZ
+   */
   p5.prototype.accelerationZ = 0;
 
+  /**
+   * The system variable pAccelerationX always contains the acceleration of the
+   * device along the x axis in the frame previous to the current frame. Value
+   * is represented as meters per second squared.
+   *
+   * @property pAccelerationX
+   */
   p5.prototype.pAccelerationX = 0;
+
+  /**
+   * The system variable pAccelerationY always contains the acceleration of the
+   * device along the y axis in the frame previous to the current frame. Value
+   * is represented as meters per second squared.
+   *
+   * @property pAccelerationY
+   */
   p5.prototype.pAccelerationY = 0;
+
+  /**
+   * The system variable pAccelerationZ always contains the acceleration of the
+   * device along the z axis in the frame previous to the current frame. Value
+   * is represented as meters per second squared.
+   *
+   * @property pAccelerationZ
+   */
   p5.prototype.pAccelerationZ = 0;
 
+  /**
+   * _updatePAccelerations updates the pAcceleration values
+   *
+   * @private
+   */
   p5.prototype._updatePAccelerations = function(){
     this._setProperty('pAccelerationX', this.accelerationX);
     this._setProperty('pAccelerationY', this.accelerationY);
@@ -22,6 +83,13 @@ define(function (require){
 
   var move_threshold = 0.5;
 
+  /**
+   * The setMoveThreshold() function is used to set the movement threshold for
+   * the onDeviceMove() function.
+   *
+   * @method setMoveThreshold
+   * @param {number} value The threshold value
+   */
   p5.prototype.setMoveThreshold = function(val){
     if(typeof val === 'number'){
       move_threshold = val;
@@ -31,6 +99,57 @@ define(function (require){
   var old_max_axis = '';
   var new_max_axis = '';
 
+  /**
+   * The onDeviceMove() function is called when the devices orientation changes
+   * by more than the threshold value.
+   * @method onDeviceMove
+   * @example
+   * <div>
+   * <code>
+   * // Run this example on a mobile device
+   * // Move the device around
+   * // to change the value.
+   *
+   * var value = 0;
+   * function draw() {
+   *   fill(value);
+   *   rect(25, 25, 50, 50);
+   * }
+   * function onDeviceMove() {
+   *   value = value + 5;
+   *   if (value > 255) {
+   *     value = 0;
+   *   }
+   * }
+   * </code>
+   * </div>
+   */
+
+  /**
+   * The onDeviceTurn() function is called when the device rotates by
+   * more than 90 degrees.
+   * @method onDeviceTurn
+   * @example
+   * <div>
+   * <code>
+   * // Run this example on a mobile device
+   * // Rotate the device by 90 degrees
+   * // to change the value.
+   *
+   * var value = 0;
+   * function draw() {
+   *   fill(value);
+   *   rect(25, 25, 50, 50);
+   * }
+   * function onDeviceTurn() {
+   *   value = value + 5;
+   *   if (value > 255) {
+   *     value = 0;
+   *   }
+   * }
+   * </code>
+   * </div>
+   */
   p5.prototype.ondevicemotion = function (e) {
     this._setProperty('accelerationX', e.accelerationIncludingGravity.x);
     this._setProperty('accelerationY', e.accelerationIncludingGravity.y);
@@ -73,7 +192,7 @@ define(function (require){
       if(Math.abs(this.accelerationZ) > max_val){
         new_max_axis = 'z'; //max_val is now irrelevant
       }
-      
+
       if(old_max_axis !== '' && old_max_axis !== new_max_axis){
         onDeviceTurn(new_max_axis);
       }