Merge pull request #978 from pagameba/doc-deviceorientation

More comprehensive docs for ol.DeviceOrientation

src/ol/deviceorientation.js

@@ -21,6 +21,51 @@ ol.DeviceOrientationProperty = {
 
 
 /**
+ * The ol.DeviceOrientation class provides access to DeviceOrientation
+ * information and events, see the [HTML 5 DeviceOrientation Specification](
+ * http://dev.w3.org/geo/api/spec-source-orientation) for more details.
+ *
+ * Many new computers, and especially mobile phones
+ * and tablets, provide hardware support for device orientation. Web
+ * developers targetting mobile devices will be especially interested in this
+ * class.
+ *
+ * Device orientation data are relative to a common starting point. For mobile
+ * devices, the starting point is to lay your phone face up on a table with the
+ * top of the phone pointing north. This represents the zero state. All
+ * angles are then relative to this state. For computers, it is the same except
+ * the screen is open at 90 degrees.
+ *
+ * Device orientation is reported as three angles - `alpha`, `beta`, and
+ * `gamma` - relative to the starting position along the three planar axes X, Y
+ * and Z. The X axis runs from the left edge to the right edge through the
+ * middle of the device. Similarly, the Y axis runs from the bottom to the top
+ * of the device through the middle. The Z axis runs from the back to the front
+ * through the middle. In the starting position, the X axis points to the
+ * right, the Y axis points away from you and the Z axis points straight up
+ * from the device lying flat.
+ *
+ * The three angles representing the device orientation are relative to the
+ * three axes. `alpha` indicates how much the device has been rotated around the
+ * Z axis, which is commonly interpreted as the compass heading (see note
+ * below). `beta` indicates how much the device has been rotated around the X
+ * axis, or how much it is tilted from front to back.  `gamma` indicates how
+ * much the device has been rotated around the Y axis, or how much it is tilted
+ * from left to right.
+ *
+ * For most browsers, the `alpha` value returns the compass heading so if the
+ * device points north, it will be 0.  With Safari on iOS, the 0 value of
+ * `alpha` is calculated from when device orientation was first requested.
+ * ol.DeviceOrientation provides the `heading` property which normalizes this
+ * behavior across all browsers for you.
+ *
+ * It is important to note that the HTML 5 DeviceOrientation specification
+ * indicates that `alpha`, `beta` and `gamma` are in degrees while the
+ * equivalent properties in ol.DeviceOrientation are in radians for consistency
+ * with all other uses of angles throughout OpenLayers.
+ *
+ * @see http://dev.w3.org/geo/api/spec-source-orientation
+ *
  * @constructor
  * @extends {ol.Object}
  * @param {ol.DeviceOrientationOptions=} opt_options Options.
@@ -57,7 +102,7 @@ ol.DeviceOrientation.prototype.disposeInternal = function() {
 
 
 /**
- * Is supported.
+ * Indicates if DeviceOrientation is supported in the user's browser.
  * @const
  * @type {boolean}
  */
@@ -91,7 +136,8 @@ ol.DeviceOrientation.prototype.orientationChange_ = function(browserEvent) {
 
 
 /**
- * @return {number|undefined} alpha.
+ * @return {number|undefined} The alpha value of the DeviceOrientation,
+ * in radians.
  */
 ol.DeviceOrientation.prototype.getAlpha = function() {
   return /** @type {number|undefined} */ (
@@ -104,7 +150,8 @@ goog.exportProperty(
 
 
 /**
- * @return {number|undefined} beta.
+ * @return {number|undefined} The beta value of the DeviceOrientation,
+ * in radians.
  */
 ol.DeviceOrientation.prototype.getBeta = function() {
   return /** @type {number|undefined} */ (
@@ -117,7 +164,8 @@ goog.exportProperty(
 
 
 /**
- * @return {number|undefined} gamma.
+ * @return {number|undefined} The gamma value of the DeviceOrientation,
+ * in radians.
  */
 ol.DeviceOrientation.prototype.getGamma = function() {
   return /** @type {number|undefined} */ (
@@ -130,7 +178,8 @@ goog.exportProperty(
 
 
 /**
- * @return {number|undefined} heading.
+ * @return {number|undefined} The heading of the device relative to
+ * north, in radians, normalizing for different browser behavior.
  */
 ol.DeviceOrientation.prototype.getHeading = function() {
   return /** @type {number|undefined} */ (
@@ -144,7 +193,7 @@ goog.exportProperty(
 
 /**
  * Are we tracking the device's orientation?
- * @return {boolean} tracking.
+ * @return {boolean} The current tracking state, true if tracking is on.
  */
 ol.DeviceOrientation.prototype.getTracking = function() {
   return /** @type {boolean} */ (
@@ -174,7 +223,8 @@ ol.DeviceOrientation.prototype.handleTrackingChanged_ = function() {
 
 
 /**
- * @param {boolean} tracking Enable or disable tracking.
+ * Enable or disable tracking of DeviceOrientation events.
+ * @param {boolean} tracking True to enable and false to disable tracking.
  */
 ol.DeviceOrientation.prototype.setTracking = function(tracking) {
   this.set(ol.DeviceOrientationProperty.TRACKING, tracking);