From f9ba90f4cab0439c1a711f7f9bd2f19322840b21 Mon Sep 17 00:00:00 2001 From: Paul Spencer Date: Wed, 4 Sep 2013 21:28:59 -0400 Subject: [PATCH 1/3] More comprehensive docs for ol.DeviceOrientation Adding an extended class description of DeviceOrientation along with some additional details in the property accessors. --- src/ol/deviceorientation.js | 61 ++++++++++++++++++++++++++++++++++--- 1 file changed, 56 insertions(+), 5 deletions(-) diff --git a/src/ol/deviceorientation.js b/src/ol/deviceorientation.js index 8e40fdd47d..182c1d9c33 100644 --- a/src/ol/deviceorientation.js +++ b/src/ol/deviceorientation.js @@ -21,6 +21,53 @@ ol.DeviceOrientationProperty = { /** + * @class + * The ol.DeviceOrientation class provides access to HTML 5 DeviceOrientation + * information and events. + * + * See http://dev.w3.org/geo/api/spec-source-orientation. + * + * 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 +104,7 @@ ol.DeviceOrientation.prototype.disposeInternal = function() { /** - * Is supported. + * Indicates if DeviceOrientation is supported in the user's browser. * @const * @type {boolean} */ @@ -91,7 +138,8 @@ ol.DeviceOrientation.prototype.orientationChange_ = function(browserEvent) { /** - * @return {number|undefined} alpha. + * @return {number|undefined} alpha The alpha value of the DeviceOrientation, + * in radians. */ ol.DeviceOrientation.prototype.getAlpha = function() { return /** @type {number|undefined} */ ( @@ -104,7 +152,8 @@ goog.exportProperty( /** - * @return {number|undefined} beta. + * @return {number|undefined} beta The beta value of the DeviceOrientation, + * in radians. */ ol.DeviceOrientation.prototype.getBeta = function() { return /** @type {number|undefined} */ ( @@ -117,7 +166,8 @@ goog.exportProperty( /** - * @return {number|undefined} gamma. + * @return {number|undefined} gamma The gamma value of the DeviceOrientation, + * in radians. */ ol.DeviceOrientation.prototype.getGamma = function() { return /** @type {number|undefined} */ ( @@ -130,7 +180,8 @@ goog.exportProperty( /** - * @return {number|undefined} heading. + * @return {number|undefined} heading The heading of the device relative to + * north, in radians, normalizing for different browser behavior. */ ol.DeviceOrientation.prototype.getHeading = function() { return /** @type {number|undefined} */ ( From 74158e52bea9e5168baf329a2e1502bce377f17a Mon Sep 17 00:00:00 2001 From: Paul Spencer Date: Thu, 5 Sep 2013 07:57:16 -0400 Subject: [PATCH 2/3] Update based on comments This removes @class and fixes the return type pattern to match the project standard. There are a couple of minor changes to the text as well. --- src/ol/deviceorientation.js | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/src/ol/deviceorientation.js b/src/ol/deviceorientation.js index 182c1d9c33..6b34fc2777 100644 --- a/src/ol/deviceorientation.js +++ b/src/ol/deviceorientation.js @@ -21,12 +21,9 @@ ol.DeviceOrientationProperty = { /** - * @class * The ol.DeviceOrientation class provides access to HTML 5 DeviceOrientation * information and events. * - * See http://dev.w3.org/geo/api/spec-source-orientation. - * * 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 @@ -138,7 +135,7 @@ ol.DeviceOrientation.prototype.orientationChange_ = function(browserEvent) { /** - * @return {number|undefined} alpha The alpha value of the DeviceOrientation, + * @return {number|undefined} The alpha value of the DeviceOrientation, * in radians. */ ol.DeviceOrientation.prototype.getAlpha = function() { @@ -152,7 +149,7 @@ goog.exportProperty( /** - * @return {number|undefined} beta The beta value of the DeviceOrientation, + * @return {number|undefined} The beta value of the DeviceOrientation, * in radians. */ ol.DeviceOrientation.prototype.getBeta = function() { @@ -166,7 +163,7 @@ goog.exportProperty( /** - * @return {number|undefined} gamma The gamma value of the DeviceOrientation, + * @return {number|undefined} The gamma value of the DeviceOrientation, * in radians. */ ol.DeviceOrientation.prototype.getGamma = function() { @@ -180,7 +177,7 @@ goog.exportProperty( /** - * @return {number|undefined} heading The heading of the device relative to + * @return {number|undefined} The heading of the device relative to * north, in radians, normalizing for different browser behavior. */ ol.DeviceOrientation.prototype.getHeading = function() { @@ -195,7 +192,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} */ ( @@ -225,7 +222,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); From a0ca05d18e7de859409f4be6f2ab824a2ac87211 Mon Sep 17 00:00:00 2001 From: Paul Spencer Date: Thu, 5 Sep 2013 09:01:49 -0400 Subject: [PATCH 3/3] Use markdown format for inline links --- src/ol/deviceorientation.js | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/ol/deviceorientation.js b/src/ol/deviceorientation.js index 6b34fc2777..3b86d5bba4 100644 --- a/src/ol/deviceorientation.js +++ b/src/ol/deviceorientation.js @@ -21,8 +21,9 @@ ol.DeviceOrientationProperty = { /** - * The ol.DeviceOrientation class provides access to HTML 5 DeviceOrientation - * information and events. + * 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