Merge pull request openlayers#2178 from probins/classdesc

Use @classdesc notation.
pagameba · Jun 9, 2014 · 2a42e77 · 2a42e77
2 parents ee38f8f + 41d9f03
commit 2a42e77
Show file tree

Hide file tree

Showing 114 changed files with 372 additions and 43 deletions.
diff --git a/build.py b/build.py
@@ -342,7 +342,7 @@ def serve_precommit(t):
 def build_lint_src_timestamp(t):
     t.run('%(GJSLINT)s',
           '--jslint_error=all',
-          '--custom_jsdoc_tags=event,fires,todo,function',
+          '--custom_jsdoc_tags=event,fires,todo,function,classdesc',
           '--strict',
           t.newer(t.dependencies))
     t.touch()

diff --git a/src/ol/attribution.js b/src/ol/attribution.js
@@ -5,18 +5,19 @@ goog.require('ol.TileRange');
 
 
 /**
- * Create a new attribution to be associated with a layer source.
+ * @classdesc
+ * An attribution for a layer source.
  *
  * Example:
  *
  *     source: new ol.source.OSM({
  *       attributions: [
- *       new ol.Attribution({
- *         html: 'All maps &copy; ' +
- *             '<a href="http://www.opencyclemap.org/">OpenCycleMap</a>'
- *       }),
- *       ol.source.OSM.DATA_ATTRIBUTION
- *     ],
+ *         new ol.Attribution({
+ *           html: 'All maps &copy; ' +
+ *               '<a href="http://www.opencyclemap.org/">OpenCycleMap</a>'
+ *         }),
+ *         ol.source.OSM.DATA_ATTRIBUTION
+ *       ],
  *     ..
  *
  * @constructor

diff --git a/src/ol/collection.js b/src/ol/collection.js
@@ -65,7 +65,12 @@ ol.CollectionProperty = {
 
 
 /**
- * A mutable MVC Array.
+ * @classdesc
+ * Adds methods to standard Array; changes (add/remove) to the Collection
+ * trigger events. Because a Collection is itself an {@link ol.Object}, it
+ * can be bound to any other Object or Collection such that a change in one
+ * will automatically be reflected in the other.
+ *
  * @constructor
  * @extends {ol.Object}
  * @fires ol.CollectionEvent

diff --git a/src/ol/control/attributioncontrol.js b/src/ol/control/attributioncontrol.js
@@ -13,10 +13,12 @@ goog.require('ol.css');
 
 
 /**
- * Create a new attribution control to show all the attributions associated
- * with the layer sources in the map. A default map has this control included.
- * By default it will show in the bottom right portion of the map, but it can
+ * @classdesc
+ * Control to show all the attributions associated with the layer sources
+ * in the map. This control is one of the default controls included in maps.
+ * By default it will show in the bottom right portion of the map, but this can
  * be changed by using a css selector for `.ol-attribution`.
+ *
  * @constructor
  * @extends {ol.control.Control}
  * @param {olx.control.AttributionOptions=} opt_options Attribution options.

diff --git a/src/ol/control/control.js b/src/ol/control/control.js
@@ -9,8 +9,12 @@ goog.require('ol.Object');
 
 
 /**
- * Something to be painted over the map to provide a means for interaction
- * (buttons) or to show annotations (status bars).
+ * @classdesc
+ * Abstract parent class for controls.
+ * A control is a visible widget with a DOM element in a fixed position on the
+ * screen. They can involve user input (buttons), or be informational only;
+ * the position is determined using CSS. By default these are part of the map
+ * container, but can use any outside DOM element.
  *
  * @constructor
  * @extends {ol.Object}

diff --git a/src/ol/control/controldefaults.js b/src/ol/control/controldefaults.js
@@ -8,12 +8,15 @@ goog.require('ol.control.Zoom');
 
 
 /**
- * Set of default controls. Unless configured otherwise, this returns a
- * collection containing an instance of each of the following controls:
+ * @classdesc
+ * Set of controls included in maps by default. Unless configured otherwise,
+ * this returns a collection containing an instance of each of the following
+ * controls:
  * * {@link ol.control.Zoom}
  * * {@link ol.control.Rotate}
  * * {@link ol.control.Attribution}
  * * {@link ol.control.Logo}
+ *
  * @param {olx.control.DefaultsOptions=} opt_options Defaults options.
  * @return {ol.Collection} Controls.
  * @todo api

diff --git a/src/ol/control/fullscreencontrol.js b/src/ol/control/fullscreencontrol.js
@@ -15,6 +15,7 @@ goog.require('ol.pointer.PointerEventHandler');
 
 
 /**
+ * @classdesc
  * Provides a button that when clicked fills up the full screen with the map.
  * When in full screen mode, a close button is shown to exit full screen mode.
  * The [Fullscreen API](http://www.w3.org/TR/fullscreen/) is used to

diff --git a/src/ol/control/logocontrol.js b/src/ol/control/logocontrol.js
@@ -10,10 +10,12 @@ goog.require('ol.css');
 
 
 /**
+ * @classdesc
  * Shows a logo for all the layer sources in the map that have a logo
  * associated with them, such as Bing. This control is part of a default map.
  * By default it will show in the bottom-left portion of the map, but it can
  * be styled by using a css selector for `.ol-logo`.
+ *
  * @constructor
  * @extends {ol.control.Control}
  * @param {olx.control.LogoOptions=} opt_options Logo options.

diff --git a/src/ol/control/mousepositioncontrol.js b/src/ol/control/mousepositioncontrol.js
@@ -28,10 +28,11 @@ ol.control.MousePositionProperty = {
 
 
 /**
- * Create a new control to show the position of the mouse in the map's
- * projection (or any other supplied projection). By default the control is
- * shown in the top right corner of the map but this can be changed by using
- * a css selector `.ol-mouse-position`.
+ * @classdesc
+ * A control to show the 2D coordinates of the mouse cursor. By default, these
+ * are in the view projection, but can be in any supported projection.
+ * By default the control is shown in the top right corner of the map, but this
+ * can be changed by using the css selector `.ol-mouse-position`.
  *
  * @constructor
  * @extends {ol.control.Control}

diff --git a/src/ol/control/rotatecontrol.js b/src/ol/control/rotatecontrol.js
@@ -17,8 +17,10 @@ goog.require('ol.pointer.PointerEventHandler');
 
 
 /**
- * Create a new control with a button, to reset rotation to 0.
+ * @classdesc
+ * A button control to reset rotation to 0.
  * To style this control use css selector `.ol-rotate`.
+ *
  * @constructor
  * @extends {ol.control.Control}
  * @param {olx.control.RotateOptions=} opt_options Rotate options.

diff --git a/src/ol/control/scalelinecontrol.js b/src/ol/control/scalelinecontrol.js
@@ -42,9 +42,10 @@ ol.control.ScaleLineUnits = {
 
 
 /**
- * Create a control to help users estimate distances on a map.
- * By default it will show in the bottom left portion of the map, but it can
- * be changed by using a css selector for `.ol-scale-line`.
+ * @classdesc
+ * A control displaying rough x-axis distances.
+ * By default it will show in the bottom left portion of the map, but this can
+ * be changed by using the css selector `.ol-scale-line`.
  *
  * @constructor
  * @extends {ol.control.Control}

diff --git a/src/ol/control/zoomcontrol.js b/src/ol/control/zoomcontrol.js
@@ -17,9 +17,11 @@ goog.require('ol.pointer.PointerEventHandler');
 
 
 /**
- * Create a new control with 2 buttons, one for zoom in and one for zoom out.
- * This control is part of the default controls of a map. To style this control
+ * @classdesc
+ * A control with 2 buttons, one for zoom in and one for zoom out.
+ * This control is one of the default controls of a map. To style this control
  * use css selectors `.ol-zoom-in` and `.ol-zoom-out`.
+ *
  * @constructor
  * @extends {ol.control.Control}
  * @param {olx.control.ZoomOptions=} opt_options Zoom options.

diff --git a/src/ol/control/zoomslidercontrol.js b/src/ol/control/zoomslidercontrol.js
@@ -23,6 +23,7 @@ goog.require('ol.easing');
 
 
 /**
+ * @classdesc
  * A slider type of control for zooming.
  *
  * Example:

diff --git a/src/ol/control/zoomtoextentcontrol.js b/src/ol/control/zoomtoextentcontrol.js
@@ -14,9 +14,10 @@ goog.require('ol.pointer.PointerEventHandler');
 
 
 /**
- * Create a control that adds a button, which, when pressed, changes
- * the map view to a specific extent. To style this control use the
- * css selector `.ol-zoom-extent`.
+ * @classdesc
+ * A button control which, when pressed, changes the map view to a specific
+ * extent. To style this control use the css selector `.ol-zoom-extent`.
+ *
  * @constructor
  * @extends {ol.control.Control}
  * @param {olx.control.ZoomToExtentOptions=} opt_options Options.

diff --git a/src/ol/deviceorientation.js b/src/ol/deviceorientation.js
@@ -21,6 +21,7 @@ ol.DeviceOrientationProperty = {
 
 
 /**
+ * @classdesc
  * The ol.DeviceOrientation class provides access to DeviceOrientation
  * information and events, see the [HTML 5 DeviceOrientation Specification](
  * http://www.w3.org/TR/orientation-event/) for more details.

diff --git a/src/ol/dom/input.js b/src/ol/dom/input.js
@@ -18,6 +18,7 @@ ol.dom.InputProperty = {
 
 
 /**
+ * @classdesc
  * Helper class for binding HTML input to an {@link ol.Object}.
  *
  * Example:

diff --git a/src/ol/feature.js b/src/ol/feature.js
@@ -16,6 +16,12 @@ goog.require('ol.style.Style');
 
 
 /**
+ * @classdesc
+ * A vector object for geographical features with a geometry and other
+ * attribute properties, similar to the features in vector file formats like
+ * GeoJSON.
+ * Features can be styled individually or use the style of their vector layer.
+ *
  * @constructor
  * @extends {ol.Object}
  * @fires change Triggered when the geometry or style of the feature changes.

diff --git a/src/ol/featureoverlay.js b/src/ol/featureoverlay.js
@@ -15,6 +15,14 @@ goog.require('ol.style.ImageState');
 
 
 /**
+ * @classdesc
+ * A mechanism for changing the style of a small number of features on a
+ * temporary basis, for example highlighting. This is necessary with the Canvas
+ * renderer, where, unlike in SVG, features cannot be individually referenced.
+ * See examples/vector-layers for an example: create a FeatureOverlay with a
+ * different style, copy the feature(s) you want rendered in this different
+ * style into it, and then remove them again when you're finished.
+ *
  * @constructor
  * @param {olx.FeatureOverlayOptions=} opt_options Options.
  * @todo api

diff --git a/src/ol/format/featureformat.js b/src/ol/format/featureformat.js
@@ -5,7 +5,9 @@ goog.require('goog.functions');
 
 
 /**
- * ol.format.Feature subclasses provide the ability to decode and encode
+ * @classdesc
+ * Abstract base class for feature formats.
+ * {ol.format.Feature} subclasses provide the ability to decode and encode
  * {@link ol.Feature} objects from a variety of commonly used geospatial
  * file formats.  See the documentation for each format for more details.
  *

diff --git a/src/ol/format/geojsonformat.js b/src/ol/format/geojsonformat.js
@@ -21,7 +21,8 @@ goog.require('ol.proj');
 
 
 /**
- * Provide access to features stored in the GeoJSON format.
+ * @classdesc
+ * Feature format for reading and writing data in the GeoJSON format.
  *
  * @constructor
  * @extends {ol.format.JSONFeature}

diff --git a/src/ol/format/gmlformat.js b/src/ol/format/gmlformat.js
@@ -24,6 +24,9 @@ goog.require('ol.xml');
 
 
 /**
+ * @classdesc
+ * Feature format for reading and writing data in the GML format.
+ *
  * @constructor
  * @param {olx.format.GMLOptions=} opt_options
  *     Optional configuration object.

diff --git a/src/ol/format/gpxformat.js b/src/ol/format/gpxformat.js
@@ -17,6 +17,9 @@ goog.require('ol.xml');
 
 
 /**
+ * @classdesc
+ * Feature format for reading and writing data in the GPX format.
+ *
  * @constructor
  * @extends {ol.format.XMLFeature}
  * @todo api

diff --git a/src/ol/format/igcformat.js b/src/ol/format/igcformat.js
@@ -22,6 +22,9 @@ ol.format.IGCZ = {
 
 
 /**
+ * @classdesc
+ * Feature format for `*.igc` flight recording files.
+ *
  * @constructor
  * @extends {ol.format.TextFeature}
  * @param {olx.format.IGCOptions=} opt_options Options.

diff --git a/src/ol/format/jsonfeatureformat.js b/src/ol/format/jsonfeatureformat.js
@@ -9,6 +9,9 @@ goog.require('ol.format.FormatType');
 
 
 /**
+ * @classdesc
+ * Abstract base class for JSON feature formats.
+ *
  * @constructor
  * @extends {ol.format.Feature}
  */

diff --git a/src/ol/format/kmlformat.js b/src/ol/format/kmlformat.js
@@ -51,6 +51,9 @@ ol.format.KMLGxTrackObject_;
 
 
 /**
+ * @classdesc
+ * Feature format for reading and writing data in the KML format.
+ *
  * @constructor
  * @extends {ol.format.XMLFeature}
  * @param {olx.format.KMLOptions=} opt_options Options.

diff --git a/src/ol/format/osmxmlformat.js b/src/ol/format/osmxmlformat.js
@@ -16,6 +16,9 @@ goog.require('ol.xml');
 
 
 /**
+ * @classdesc
+ * Feature format for reading and writing data in the OSMXML format.
+ *
  * @constructor
  * @extends {ol.format.XMLFeature}
  * @todo api

diff --git a/src/ol/format/textfeatureformat.js b/src/ol/format/textfeatureformat.js
@@ -7,6 +7,9 @@ goog.require('ol.format.FormatType');
 
 
 /**
+ * @classdesc
+ * Abstract base class for text feature formats.
+ *
  * @constructor
  * @extends {ol.format.Feature}
  */

diff --git a/src/ol/format/topojsonformat.js b/src/ol/format/topojsonformat.js
@@ -15,6 +15,9 @@ goog.require('ol.proj');
 
 
 /**
+ * @classdesc
+ * Feature format for reading and writing data in the TopoJSON format.
+ *
  * @constructor
  * @extends {ol.format.JSONFeature}
  * @param {olx.format.TopoJSONOptions=} opt_options Options.

diff --git a/src/ol/format/wfsformat.js b/src/ol/format/wfsformat.js
@@ -13,6 +13,9 @@ goog.require('ol.xml');
 
 
 /**
+ * @classdesc
+ * Feature format for reading and writing data in the WFS format.
+ *
  * @constructor
  * @param {olx.format.WFSOptions=} opt_options
  *     Optional configuration object.

diff --git a/src/ol/format/wmscapabilitiesformat.js b/src/ol/format/wmscapabilitiesformat.js
@@ -13,6 +13,9 @@ goog.require('ol.xml');
 
 
 /**
+ * @classdesc
+ * Format for reading WMS capabilities data
+ *
  * @constructor
  * @extends {ol.format.XML}
  * @todo api

diff --git a/src/ol/format/xmlfeatureformat.js b/src/ol/format/xmlfeatureformat.js
@@ -10,6 +10,9 @@ goog.require('ol.xml');
 
 
 /**
+ * @classdesc
+ * Abstract base class for XML feature formats.
+ *
  * @constructor
  * @extends {ol.format.Feature}
  */

diff --git a/src/ol/format/xmlformat.js b/src/ol/format/xmlformat.js
@@ -6,6 +6,9 @@ goog.require('ol.xml');
 
 
 /**
+ * @classdesc
+ * Generic format for reading non-feature XML data
+ *
  * @constructor
  */
 ol.format.XML = function() {

diff --git a/src/ol/geolocation.js b/src/ol/geolocation.js
@@ -35,6 +35,7 @@ ol.GeolocationProperty = {
 
 
 /**
+ * @classdesc
  * Helper class for providing HTML5 Geolocation capabilities.
  * The [Geolocation API](http://www.w3.org/TR/geolocation-API/)
  * is used to locate a user's position.
-Original file line number
+Diff line change
@@ Expand Up / @@ -23,6 +23,7 @@ goog.require('ol.easing'); @@
     /**
+     * @classdesc
      * A slider type of control for zooming.
      *
      * Example:
@@ Expand Down @@