Merge pull request #86 from geops/api-docs-comments

Some comments (no changes to code)

src/ol/browserfeature.js

@@ -11,7 +11,9 @@ ol.ASSUME_TOUCH = false;
  * @type {Object}
  */
 ol.BrowserFeature = {
-  // Do we have touch events?
+  /**
+   * @type {boolean} True if browser supports touch events
+   */
   HAS_TOUCH: ol.ASSUME_TOUCH ||
       (document && 'ontouchstart' in document.documentElement)
 };

src/ol/color.js

@@ -6,10 +6,10 @@ goog.require('goog.color');
 
 /**
  * @constructor
- * @param {number} r Red.
- * @param {number} g Green.
- * @param {number} b Blue.
- * @param {number} a Alpha.
+ * @param {number} r Red, 0 to 255.
+ * @param {number} g Green, 0 to 255.
+ * @param {number} b Blue, 0 to 255.
+ * @param {number} a Alpha, 0 (fully transparent) to 255 (fully opaque).
  */
 ol.Color = function(r, g, b, a) {
 

src/ol/control/control.js

@@ -14,6 +14,9 @@ ol.control.ControlOptions;
 
 
 /**
+ * A thing which is painted over the map to provide a means for interaction
+ * (buttons) of show annotations (status bars).
+ *
  * @constructor
  * @extends {goog.Disposable}
  * @param {ol.control.ControlOptions} controlOptions Control options.
@@ -67,6 +70,10 @@ ol.control.Control.prototype.getMap = function() {
 
 
 /**
+ * Removes the control from its current map and attaches it to the new map.
+ * Subtypes might also wish set up event handlers to get notified about changes
+ * to the map here.
+ *
  * @param {ol.Map} map Map.
  */
 ol.control.Control.prototype.setMap = function(map) {

src/ol/coordinate.js

@@ -13,6 +13,8 @@ ol.CoordinateFormatType;
 
 
 /**
+ * Two dimensional coordinate which does not know its projection.
+ *
  * @constructor
  * @extends {goog.math.Vec2}
  * @param {number} x X.

src/ol/coveragearea.js

@@ -5,6 +5,8 @@ goog.require('ol.Extent');
 
 
 /**
+ * Represents a rectangular area.
+ *
  * @constructor
  * @param {ol.Extent} extent Extent.
  */

src/ol/extent.js

@@ -7,6 +7,9 @@ goog.require('ol.TransformFunction');
 
 
 /**
+ * Rectangular extent which is not rotated. An extent does not know its
+ * projection.
+ *
  * @constructor
  * @extends {ol.Rectangle}
  * @param {number} minX Minimum X.
@@ -21,6 +24,8 @@ goog.inherits(ol.Extent, ol.Rectangle);
 
 
 /**
+ * Builds an extent that includes all given coordinates.
+ *
  * @param {...ol.Coordinate} var_args Coordinates.
  * @return {!ol.Extent} Bounding extent.
  */
@@ -41,6 +46,8 @@ ol.Extent.boundingExtent = function(var_args) {
 
 
 /**
+ * Checks if the given coordinate is contained or on the edge of the extent.
+ *
  * @param {ol.Coordinate} coordinate Coordinate.
  * @return {boolean} Contains.
  */

src/ol/projection.js

@@ -131,6 +131,9 @@ ol.Projection.transforms_ = {};
 
 
 /**
+ * Registers transformation functions that don't alter coordinates. Those allow
+ * to transform between projections with equal meaning.
+ *
  * @param {Array.<ol.Projection>} projections Projections.
  * @private
  */
@@ -148,10 +151,15 @@ ol.Projection.addEquivalentProjections_ = function(projections) {
 
 
 /**
- * @param {Array.<ol.Projection>} projections1 Projections.
- * @param {Array.<ol.Projection>} projections2 Projections.
- * @param {ol.TransformFunction} forwardTransform Forward transform.
- * @param {ol.TransformFunction} inverseTransform Inverse transform.
+ * Registers transformation functions to convert coordinates in any projection
+ * in projection1 to any projection in projection2.
+ *
+ * @param {Array.<ol.Projection>} projections1 Projections with equal meaning.
+ * @param {Array.<ol.Projection>} projections2 Projections with equal meaning.
+ * @param {ol.TransformFunction} forwardTransform Transformation from any
+ *   projection in projection1 to any projection in projection2.
+ * @param {ol.TransformFunction} inverseTransform Transform from any projection
+ *   in projection2 to any projection in projection1..
  * @private
  */
 ol.Projection.addEquivalentTransforms_ =
@@ -217,6 +225,9 @@ ol.Projection.createProjection = function(projection, defaultCode) {
 
 
 /**
+ * Registers a conversion function to convert coordinates from the source
+ * projection to the destination projection.
+ *
  * @param {ol.Projection} source Source.
  * @param {ol.Projection} destination Destination.
  * @param {ol.TransformFunction} transformFn Transform.
@@ -236,7 +247,8 @@ ol.Projection.addTransform = function(source, destination, transformFn) {
 
 
 /**
- * @param {string} code Code.
+ * @param {string} code Code which is a combination of authority and identifier
+ *   such as “EPSG:4326”.
  * @return {ol.Projection} Projection.
  */
 ol.Projection.getFromCode = function(code) {
@@ -270,6 +282,10 @@ ol.Projection.getProj4jsProjectionFromCode_ = function(code) {
 
 
 /**
+ * Checks if two projections are the same, that is every coordinate in one
+ * projection does represent the same geographic point as the same coordinate in
+ * the other projection.
+ *
  * @param {ol.Projection} projection1 Projection 1.
  * @param {ol.Projection} projection2 Projection 2.
  * @return {boolean} Equivalent.
@@ -287,6 +303,9 @@ ol.Projection.equivalent = function(projection1, projection2) {
 
 
 /**
+ * Searches a function that can be used to convert coordinates from the source
+ * projection to the destination projection.
+ *
  * @param {ol.Projection} source Source.
  * @param {ol.Projection} destination Destination.
  * @return {ol.TransformFunction} Transform.
@@ -339,6 +358,10 @@ ol.Projection.getTransform = function(source, destination) {
 
 
 /**
+ * Given the projection codes this method searches for a transformation function
+ * to convert coordinate from the source projection to the destination
+ * projection.
+ *
  * @param {string} sourceCode Source code.
  * @param {string} destinationCode Destination code.
  * @return {ol.TransformFunction} Transform.
@@ -351,7 +374,7 @@ ol.Projection.getTransformFromCodes = function(sourceCode, destinationCode) {
 
 
 /**
- * @return {boolean} Has Proj4js.
+ * @return {boolean} True if Proj4js is available and enabled.
  */
 ol.Projection.isProj4jsSupported = function() {
   return ol.ENABLE_PROJ4JS && 'Proj4js' in goog.global;
@@ -360,7 +383,7 @@ ol.Projection.isProj4jsSupported = function() {
 
 /**
  * @param {ol.Coordinate} point Point.
- * @return {ol.Coordinate} Point.
+ * @return {ol.Coordinate} Unaltered point (same reference).
  */
 ol.Projection.identityTransform = function(point) {
   return point;
@@ -369,7 +392,7 @@ ol.Projection.identityTransform = function(point) {
 
 /**
  * @param {ol.Coordinate} point Point.
- * @return {ol.Coordinate} Point.
+ * @return {ol.Coordinate} Equal point (different reference).
  */
 ol.Projection.cloneTransform = function(point) {
   return new ol.Coordinate(point.x, point.y);
@@ -377,6 +400,8 @@ ol.Projection.cloneTransform = function(point) {
 
 
 /**
+ * Transforms the given point to the destination projection.
+ *
  * @param {ol.Coordinate} point Point.
  * @param {ol.Projection} source Source.
  * @param {ol.Projection} destination Destination.
@@ -410,6 +435,8 @@ ol.Projection.EPSG_3857_RADIUS = 6378137;
 
 
 /**
+ * Transformation from EPSG:4326 to EPSG:3857.
+ *
  * @param {ol.Coordinate} point Point.
  * @return {ol.Coordinate} Point.
  */
@@ -422,6 +449,8 @@ ol.Projection.forwardSphericalMercator = function(point) {
 
 
 /**
+ * Transformation from EPSG:3857 to EPSG:4326.
+ *
  * @param {ol.Coordinate} point Point.
  * @return {ol.Coordinate} Point.
  */
@@ -452,6 +481,8 @@ ol.Projection.EPSG_3857_EXTENT = new ol.Extent(
 
 
 /**
+ * Lists several projection codes with the same meaning as EPSG:3857.
+ *
  * @private
  * @type {Array.<string>}
  */
@@ -464,6 +495,8 @@ ol.Projection.EPSG_3857_LIKE_CODES_ = [
 
 
 /**
+ * Projections equal to EPSG:3857.
+ *
  * @const
  * @private
  * @type {Array.<ol.Projection>}
@@ -479,6 +512,8 @@ ol.Projection.EPSG_3857_LIKE_PROJECTIONS_ = goog.array.map(
 
 
 /**
+ * Extent of the EPSG:4326 projection which is the whole world.
+ *
  * @const
  * @private
  * @type {ol.Extent}
@@ -487,6 +522,7 @@ ol.Projection.EPSG_4326_EXTENT_ = new ol.Extent(-180, -90, 180, 90);
 
 
 /**
+ * Several projection code with the same meaning as EPSG:4326.
  * @private
  * @type {Array.<string>}
  */
@@ -498,6 +534,8 @@ ol.Projection.EPSG_4326_LIKE_CODES_ = [
 
 
 /**
+ * Projections equal to EPSG:4326.
+ *
  * @const
  * @type {Array.<ol.Projection>}
  */
@@ -511,10 +549,14 @@ ol.Projection.EPSG_4326_LIKE_PROJECTIONS = goog.array.map(
     });
 
 
+// Add transformations that don't alter coordinates to convert within set of
+// projections with equal meaning.
 ol.Projection.addEquivalentProjections_(
     ol.Projection.EPSG_3857_LIKE_PROJECTIONS_);
 ol.Projection.addEquivalentProjections_(
     ol.Projection.EPSG_4326_LIKE_PROJECTIONS);
+// Add transformations to convert EPSG:4326 like coordinates to EPSG:3857 like
+// coordinates and back.
 ol.Projection.addEquivalentTransforms_(
     ol.Projection.EPSG_4326_LIKE_PROJECTIONS,
     ol.Projection.EPSG_3857_LIKE_PROJECTIONS_,

src/ol/tile.js

@@ -24,7 +24,7 @@ ol.TileState = {
  * @constructor
  * @extends {goog.events.EventTarget}
  * @param {ol.TileCoord} tileCoord Tile coordinate.
- * @param {string} src Source.
+ * @param {string} src Image source URI.
  * @param {?string} crossOrigin Cross origin.
  */
 ol.Tile = function(tileCoord, src, crossOrigin) {
@@ -37,6 +37,8 @@ ol.Tile = function(tileCoord, src, crossOrigin) {
   this.tileCoord = tileCoord;
 
   /**
+   * Image URI
+   *
    * @private
    * @type {string}
    */
@@ -113,6 +115,8 @@ ol.Tile.prototype.getState = function() {
 
 
 /**
+ * Tracks loading or read errors.
+ *
  * @private
  */
 ol.Tile.prototype.handleImageError_ = function() {
@@ -122,6 +126,8 @@ ol.Tile.prototype.handleImageError_ = function() {
 
 
 /**
+ * Tracks successful image load.
+ *
  * @private
  */
 ol.Tile.prototype.handleImageLoad_ = function() {
@@ -132,7 +138,7 @@ ol.Tile.prototype.handleImageLoad_ = function() {
 
 
 /**
- * Load.
+ * Load not yet loaded URI.
  */
 ol.Tile.prototype.load = function() {
   if (this.state_ == ol.TileState.IDLE) {
@@ -150,6 +156,8 @@ ol.Tile.prototype.load = function() {
 
 
 /**
+ * Discards event handlers which listen for load completion or errors.
+ *
  * @private
  */
 ol.Tile.prototype.unlistenImage_ = function() {

src/ol/tilecoord.js

@@ -19,7 +19,7 @@ ol.QuadKeyCharCode = {
 /**
  * @constructor
  * @extends {ol.Coordinate}
- * @param {number} z Z.
+ * @param {number} z Zoom level.
  * @param {number} x X.
  * @param {number} y Y.
  */
@@ -28,7 +28,7 @@ ol.TileCoord = function(z, x, y) {
   goog.base(this, x, y);
 
   /**
-   * @type {number}
+   * @type {number} Zoom level
    */
   this.z = z;
 
@@ -64,7 +64,8 @@ ol.TileCoord.createFromQuadKey = function(quadKey) {
 
 
 /**
- * @param {string} str String.
+ * @param {string} str String that follows pattern “z/x/y” where x, y and z are
+ *   numbers.
  * @return {ol.TileCoord} Tile coord.
  */
 ol.TileCoord.createFromString = function(str) {