Merge pull request #3488 from tschaub/doc

Add docs for exportable symbols.
2015-04-04 23:37:17 +02:00
parent 1c471cca6c 50f71655e5
commit 228491344d
27 changed files with 208 additions and 90 deletions
--- a/src/ol/animation.js
+++ b/src/ol/animation.js
@@ -7,6 +7,8 @@ goog.require('ol.easing');


 /**
+ * Generate an animated transition that will "bounce" the resolution as it
+ * approaches the final value.
 * @param {olx.animation.BounceOptions} options Bounce options.
 * @return {ol.PreRenderFunction} Pre-render function.
 * @api
@@ -42,6 +44,7 @@ ol.animation.bounce = function(options) {


 /**
+ * Generate an animated transition while updating the view center.
 * @param {olx.animation.PanOptions} options Pan options.
 * @return {ol.PreRenderFunction} Pre-render function.
 * @api
@@ -81,6 +84,7 @@ ol.animation.pan = function(options) {


 /**
+ * Generate an animated transition while updating the view rotation.
 * @param {olx.animation.RotateOptions} options Rotate options.
 * @return {ol.PreRenderFunction} Pre-render function.
 * @api
@@ -126,6 +130,7 @@ ol.animation.rotate = function(options) {


 /**
+ * Generate an animated transition while updating the view resolution.
 * @param {olx.animation.ZoomOptions} options Zoom options.
 * @return {ol.PreRenderFunction} Pre-render function.
 * @api
--- a/src/ol/attribution.js
+++ b/src/ol/attribution.js
@@ -46,7 +46,8 @@ ol.Attribution = function(options) {


 /**
- * @return {string} HTML.
+ * Get the attribution markup.
+ * @return {string} The attribution HTML.
 * @api stable
 */
 ol.Attribution.prototype.getHTML = function() {
--- a/src/ol/collection.js
+++ b/src/ol/collection.js
@@ -115,6 +115,8 @@ ol.Collection.prototype.clear = function() {


 /**
+ * Add elements to the collection.  This pushes each item in the provided array
+ * to the end of the collection.
 * @param {Array.<T>} arr Array.
 * @return {ol.Collection.<T>} This collection.
 * @api stable
@@ -216,9 +218,9 @@ ol.Collection.prototype.push = function(elem) {


 /**
- * Removes the first occurrence of elem from the collection.
+ * Remove the first occurrence of an element from the collection.
 * @param {T} elem Element.
- * @return {T|undefined} The removed element or undefined if elem was not found.
+ * @return {T|undefined} The removed element or undefined if none found.
 * @api stable
 */
 ol.Collection.prototype.remove = function(elem) {
--- a/src/ol/coordinate.js
+++ b/src/ol/coordinate.js
@@ -280,6 +280,9 @@ ol.coordinate.squaredDistanceToSegment = function(coordinate, segment) {


 /**
+ * Format a geographic coordinate with the hemisphere, degrees, minutes, and
+ * seconds.
+ *
 * Example:
 *
 *     var coord = [7.85, 47.983333];
@@ -301,6 +304,8 @@ ol.coordinate.toStringHDMS = function(coordinate) {


 /**
+ * Format a coordinate as a comma delimited string.
+ *
 * Example without specifying fractional digits:
 *
 *     var coord = [7.85, 47.983333];
--- a/src/ol/deviceorientation.js
+++ b/src/ol/deviceorientation.js
@@ -22,8 +22,8 @@ ol.DeviceOrientationProperty = {

 /**
 * @classdesc
- * The ol.DeviceOrientation class provides access to DeviceOrientation
- * information and events, see the [HTML 5 DeviceOrientation Specification](
+ * The ol.DeviceOrientation class provides access to information from
+ * DeviceOrientation events.  See the [HTML 5 DeviceOrientation Specification](
 * http://www.w3.org/TR/orientation-event/) for more details.
 *
 * Many new computers, and especially mobile phones
@@ -137,6 +137,7 @@ ol.DeviceOrientation.prototype.orientationChange_ = function(browserEvent) {


 /**
+ * Rotation around the device z-axis (in radians).
 * @return {number|undefined} The euler angle in radians of the device from the
 *     standard Z axis.
 * @observable
@@ -153,6 +154,7 @@ goog.exportProperty(


 /**
+ * Rotation around the device x-axis (in radians).
 * @return {number|undefined} The euler angle in radians of the device from the
 *     planar X axis.
 * @observable
@@ -169,6 +171,7 @@ goog.exportProperty(


 /**
+ * Rotation around the device y-axis (in radians).
 * @return {number|undefined} The euler angle in radians of the device from the
 *     planar Y axis.
 * @observable
@@ -185,6 +188,7 @@ goog.exportProperty(


 /**
+ * The heading of the device relative to north (in radians).
 * @return {number|undefined} The heading of the device relative to north, in
 *     radians, normalizing for different browser behavior.
 * @observable
@@ -201,9 +205,8 @@ goog.exportProperty(


 /**
- * Are we tracking the device's orientation?
- * @return {boolean} The status of tracking changes to alpha, beta and gamma.
- *     If true, changes are tracked and reported immediately.
+ * Determine if orientation is being tracked.
+ * @return {boolean} Changes in device orientation are being tracked.
 * @observable
 * @api
 */
@@ -235,7 +238,7 @@ ol.DeviceOrientation.prototype.handleTrackingChanged_ = function() {


 /**
- * Enable or disable tracking of DeviceOrientation events.
+ * Enable or disable tracking of device orientation events.
 * @param {boolean} tracking The status of tracking changes to alpha, beta and
 *     gamma. If true, changes are tracked and reported immediately.
 * @observable
--- a/src/ol/easing.js
+++ b/src/ol/easing.js
@@ -4,6 +4,7 @@ goog.require('goog.fx.easing');


 /**
+ * Start slow and speed up.
 * @function
 * @param {number} t Input between 0 and 1.
 * @return {number} Output between 0 and 1.
@@ -13,6 +14,7 @@ ol.easing.easeIn = goog.fx.easing.easeIn;


 /**
+ * Start fast and slow down.
 * @function
 * @param {number} t Input between 0 and 1.
 * @return {number} Output between 0 and 1.
@@ -22,6 +24,7 @@ ol.easing.easeOut = goog.fx.easing.easeOut;


 /**
+ * Start slow, speed up, and then slow down again.
 * @function
 * @param {number} t Input between 0 and 1.
 * @return {number} Output between 0 and 1.
@@ -31,6 +34,7 @@ ol.easing.inAndOut = goog.fx.easing.inAndOut;


 /**
+ * Maintain a constant speed over time.
 * @param {number} t Input between 0 and 1.
 * @return {number} Output between 0 and 1.
 * @api
@@ -41,6 +45,9 @@ ol.easing.linear = function(t) {


 /**
+ * Start slow, speed up, and at the very end slow down again.  This has the
+ * same general behavior as {@link ol.easing.inAndOut}, but the final slowdown
+ * is delayed.
 * @param {number} t Input between 0 and 1.
 * @return {number} Output between 0 and 1.
 * @api
--- a/src/ol/extent.js
+++ b/src/ol/extent.js
@@ -45,7 +45,7 @@ ol.extent.Relationship = {


 /**
- * Builds an extent that includes all given coordinates.
+ * Build an extent that includes all given coordinates.
 *
 * @param {Array.<ol.Coordinate>} coordinates Coordinates.
 * @return {ol.Extent} Bounding extent.
@@ -151,11 +151,11 @@ ol.extent.closestSquaredDistanceXY = function(extent, x, y) {


 /**
- * Checks if the passed coordinate is contained or on the edge of the extent.
+ * Check if the passed coordinate is contained or on the edge of the extent.
 *
 * @param {ol.Extent} extent Extent.
 * @param {ol.Coordinate} coordinate Coordinate.
- * @return {boolean} Contains.
+ * @return {boolean} The coordinate is contained in the extent.
 * @api stable
 */
 ol.extent.containsCoordinate = function(extent, coordinate) {
@@ -164,11 +164,12 @@ ol.extent.containsCoordinate = function(extent, coordinate) {


 /**
- * Checks if `extent2` is contained by or on the edge of `extent1`.
+ * Check if one extent is contained by or on the edge of another.
 *
 * @param {ol.Extent} extent1 Extent 1.
 * @param {ol.Extent} extent2 Extent 2.
- * @return {boolean} Contains.
+ * @return {boolean} The first extent is contained by or on the edge of the
+ *     second.
 * @api stable
 */
 ol.extent.containsExtent = function(extent1, extent2) {
@@ -178,12 +179,12 @@ ol.extent.containsExtent = function(extent1, extent2) {


 /**
- * Checks if the passed coordinate is contained or on the edge of the extent.
+ * Check if the passed coordinate is contained or on the edge of the extent.
 *
 * @param {ol.Extent} extent Extent.
 * @param {number} x X coordinate.
 * @param {number} y Y coordinate.
- * @return {boolean} Contains.
+ * @return {boolean} The x, y values are contained in the extent.
 * @api stable
 */
 ol.extent.containsXY = function(extent, x, y) {
@@ -224,6 +225,7 @@ ol.extent.coordinateRelationship = function(extent, coordinate) {


 /**
+ * Create an empty extent.
 * @return {ol.Extent} Empty extent.
 * @api stable
 */
@@ -233,6 +235,7 @@ ol.extent.createEmpty = function() {


 /**
+ * Create a new extent or update the provided extent.
 * @param {number} minX Minimum X.
 * @param {number} minY Minimum Y.
 * @param {number} maxX Maximum X.
@@ -254,6 +257,7 @@ ol.extent.createOrUpdate = function(minX, minY, maxX, maxY, opt_extent) {


 /**
+ * Create a new empty extent or make the provided one empty.
 * @param {ol.Extent=} opt_extent Extent.
 * @return {ol.Extent} Extent.
 */
@@ -314,7 +318,7 @@ ol.extent.createOrUpdateFromRings = function(rings, opt_extent) {


 /**
- * Empties extent in place.
+ * Empty an extent in place.
 * @param {ol.Extent} extent Extent.
 * @return {ol.Extent} Extent.
 */
@@ -326,9 +330,10 @@ ol.extent.empty = function(extent) {


 /**
+ * Determine if two extents are equivalent.
 * @param {ol.Extent} extent1 Extent 1.
 * @param {ol.Extent} extent2 Extent 2.
- * @return {boolean} Equals.
+ * @return {boolean} The two extents are equivalent.
 * @api stable
 */
 ol.extent.equals = function(extent1, extent2) {
@@ -338,9 +343,10 @@ ol.extent.equals = function(extent1, extent2) {


 /**
- * @param {ol.Extent} extent1 Extent 1.
- * @param {ol.Extent} extent2 Extent 2.
- * @return {ol.Extent} Extent.
+ * Modify an extent to include another extent.
+ * @param {ol.Extent} extent1 The extent to be modified.
+ * @param {ol.Extent} extent2 The extent that will be included in the first.
+ * @return {ol.Extent} A reference to the first (extended) extent.
 * @api stable
 */
 ol.extent.extend = function(extent1, extent2) {
@@ -485,6 +491,7 @@ ol.extent.getArea = function(extent) {


 /**
+ * Get the bottom left coordinate of an extent.
 * @param {ol.Extent} extent Extent.
 * @return {ol.Coordinate} Bottom left coordinate.
 * @api stable
@@ -495,6 +502,7 @@ ol.extent.getBottomLeft = function(extent) {


 /**
+ * Get the bottom right coordinate of an extent.
 * @param {ol.Extent} extent Extent.
 * @return {ol.Coordinate} Bottom right coordinate.
 * @api stable
@@ -505,6 +513,7 @@ ol.extent.getBottomRight = function(extent) {


 /**
+ * Get the center coordinate of an extent.
 * @param {ol.Extent} extent Extent.
 * @return {ol.Coordinate} Center.
 * @api stable
@@ -582,6 +591,7 @@ ol.extent.getForViewAndSize =


 /**
+ * Get the height of an extent.
 * @param {ol.Extent} extent Extent.
 * @return {number} Height.
 * @api stable
@@ -649,8 +659,9 @@ ol.extent.getMargin = function(extent) {


 /**
- * @param {ol.Extent} extent Extent.
- * @return {ol.Size} Size.
+ * Get the size (width, height) of an extent.
+ * @param {ol.Extent} extent The extent.
+ * @return {ol.Size} The extent size.
 * @api stable
 */
 ol.extent.getSize = function(extent) {
@@ -659,6 +670,7 @@ ol.extent.getSize = function(extent) {


 /**
+ * Get the top left coordinate of an extent.
 * @param {ol.Extent} extent Extent.
 * @return {ol.Coordinate} Top left coordinate.
 * @api stable
@@ -669,6 +681,7 @@ ol.extent.getTopLeft = function(extent) {


 /**
+ * Get the top right coordinate of an extent.
 * @param {ol.Extent} extent Extent.
 * @return {ol.Coordinate} Top right coordinate.
 * @api stable
@@ -679,6 +692,7 @@ ol.extent.getTopRight = function(extent) {


 /**
+ * Get the width of an extent.
 * @param {ol.Extent} extent Extent.
 * @return {number} Width.
 * @api stable
@@ -689,9 +703,10 @@ ol.extent.getWidth = function(extent) {


 /**
+ * Determine if one extent intersects another.
 * @param {ol.Extent} extent1 Extent 1.
 * @param {ol.Extent} extent2 Extent.
- * @return {boolean} Intersects.
+ * @return {boolean} The two extents intersect.
 * @api stable
 */
 ol.extent.intersects = function(extent1, extent2) {
@@ -703,6 +718,7 @@ ol.extent.intersects = function(extent1, extent2) {


 /**
+ * Determine if an extent is empty.
 * @param {ol.Extent} extent Extent.
 * @return {boolean} Is empty.
 * @api stable
--- a/src/ol/feature.js
+++ b/src/ol/feature.js
@@ -137,10 +137,10 @@ ol.Feature.prototype.clone = function() {


 /**
- * @return {ol.geom.Geometry|undefined} Returns the Geometry associated
- *     with this feature using the current geometry name property.  By
- *     default, this is `geometry` but it may be changed by calling
- *     `setGeometryName`.
+ * Get the feature's default geometry.  A feature may have any number of named
+ * geometries.  The "default" geometry (the one that is rendered by default) is
+ * set when calling {@link ol.Feature#setGeometry}.
+ * @return {ol.geom.Geometry|undefined} The default geometry for the feature.
 * @api stable
 * @observable
 */
@@ -164,9 +164,10 @@ ol.Feature.prototype.getId = function() {


 /**
- * @return {string} Get the property name associated with the geometry for
- *     this feature.  By default, this is `geometry` but it may be changed by
- *     calling `setGeometryName`.
+ * Get the name of the feature's default geometry.  By default, the default
+ * geometry is named `geometry`.
+ * @return {string} Get the property name associated with the default geometry
+ *     for this feature.
 * @api stable
 */
 ol.Feature.prototype.getGeometryName = function() {
@@ -175,11 +176,10 @@ ol.Feature.prototype.getGeometryName = function() {


 /**
+ * Get the feature's style.  This return for this method depends on what was
+ * provided to the {@link ol.Feature#setStyle} method.
 * @return {ol.style.Style|Array.<ol.style.Style>|
- *     ol.feature.FeatureStyleFunction} Return the style as set by `setStyle`
- * in the same format that it was provided in. If `setStyle` has not been
- * called, or if it was called with `null`, then `getStyle()` will return
- * `null`.
+ *     ol.feature.FeatureStyleFunction} The feature style.
 * @api stable
 */
 ol.Feature.prototype.getStyle = function() {
@@ -188,6 +188,7 @@ ol.Feature.prototype.getStyle = function() {


 /**
+ * Get the feature's style function.
 * @return {ol.feature.FeatureStyleFunction|undefined} Return a function
 * representing the current style of this feature.
 * @api stable
@@ -223,10 +224,9 @@ ol.Feature.prototype.handleGeometryChanged_ = function() {


 /**
- * @param {ol.geom.Geometry|undefined} geometry Set the geometry for this
- * feature. This will update the property associated with the current
- * geometry property name.  By default, this is `geometry` but it can be
- * changed by calling `setGeometryName`.
+ * Set the default geometry for the feature.  This will update the property
+ * with the name returned by {@link ol.Feature#getGeometryName}.
+ * @param {ol.geom.Geometry|undefined} geometry The new geometry.
 * @api stable
 * @observable
 */
@@ -256,9 +256,11 @@ ol.Feature.prototype.setStyle = function(style) {


 /**
- * @param {number|string|undefined} id Set a unique id for this feature.
- * The id may be used to retrieve a feature from a vector source with the
- * {@link ol.source.Vector#getFeatureById} method.
+ * Set the feature id.  The feature id is considered stable and may be used when
+ * requesting features or comparing identifiers returned from a remote source.
+ * The feature id can be used with the {@link ol.source.Vector#getFeatureById}
+ * method.
+ * @param {number|string|undefined} id The feature id.
 * @api stable
 */
 ol.Feature.prototype.setId = function(id) {
@@ -268,8 +270,10 @@ ol.Feature.prototype.setId = function(id) {


 /**
- * @param {string} name Set the property name from which this feature's
- *     geometry will be fetched when calling `getGeometry`.
+ * Set the property name to be used when getting the feature's default geometry.
+ * When calling {@link ol.Feature#getGeometry}, the value of the property with
+ * this name will be returned.
+ * @param {string} name The property name of the default geometry.
 * @api stable
 */
 ol.Feature.prototype.setGeometryName = function(name) {
@@ -285,10 +289,8 @@ ol.Feature.prototype.setGeometryName = function(name) {


 /**
- * A function that takes a `{number}` representing the view's resolution. It
- * returns an Array of {@link ol.style.Style}. This way individual features
- * can be styled. The this keyword inside the function references the
- * {@link ol.Feature} to be styled.
+ * A function that returns a style given a resolution. The `this` keyword inside
+ * the function references the {@link ol.Feature} to be styled.
 *
 * @typedef {function(this: ol.Feature, number): Array.<ol.style.Style>}
 * @api stable
--- a/src/ol/featureoverlay.js
+++ b/src/ol/featureoverlay.js
@@ -96,6 +96,7 @@ ol.FeatureOverlay = function(opt_options) {


 /**
+ * Add a feature to the overlay.
 * @param {ol.Feature} feature Feature.
 * @api
 */
@@ -105,6 +106,7 @@ ol.FeatureOverlay.prototype.addFeature = function(feature) {


 /**
+ * Get the features on the overlay.
 * @return {ol.Collection.<ol.Feature>} Features collection.
 * @api
 */
@@ -114,6 +116,7 @@ ol.FeatureOverlay.prototype.getFeatures = function() {


 /**
+ * Get the map associated with the overlay.
 * @return {?ol.Map} The map with which this feature overlay is associated.
 * @api
 */
@@ -211,7 +214,8 @@ ol.FeatureOverlay.prototype.handleMapPostCompose_ = function(event) {


 /**
- * @param {ol.Feature} feature Feature.
+ * Remove a feature from the overlay.
+ * @param {ol.Feature} feature The feature to be removed.
 * @api
 */
 ol.FeatureOverlay.prototype.removeFeature = function(feature) {
@@ -230,6 +234,7 @@ ol.FeatureOverlay.prototype.render_ = function() {


 /**
+ * Set the features for the overlay.
 * @param {ol.Collection.<ol.Feature>} features Features collection.
 * @api
 */
@@ -264,6 +269,7 @@ ol.FeatureOverlay.prototype.setFeatures = function(features) {


 /**
+ * Set the map for the overlay.
 * @param {ol.Map} map Map.
 * @api
 */
--- a/src/ol/geolocation.js
+++ b/src/ol/geolocation.js
@@ -323,8 +323,8 @@ goog.exportProperty(


 /**
- * Are we tracking the user's position?
- * @return {boolean} Whether to track the device's position.
+ * Determine if the device location is being tracked.
+ * @return {boolean} The device location is being tracked.
 * @observable
 * @api stable
 */
@@ -342,8 +342,8 @@ goog.exportProperty(
 * Get the tracking options.
 * @see http://www.w3.org/TR/geolocation-API/#position-options
 * @return {GeolocationPositionOptions|undefined} PositionOptions as defined by
- *     the HTML5 Geolocation spec at
- *     {@link http://www.w3.org/TR/geolocation-API/#position_options_interface}
+ *     the [HTML5 Geolocation spec
+ *     ](http://www.w3.org/TR/geolocation-API/#position_options_interface).
 * @observable
 * @api stable
 */
@@ -374,8 +374,8 @@ goog.exportProperty(


 /**
- * Enable/disable tracking.
- * @param {boolean} tracking Whether to track the device's position.
+ * Enable or disable tracking.
+ * @param {boolean} tracking Enable tracking.
 * @observable
 * @api stable
 */
@@ -392,8 +392,8 @@ goog.exportProperty(
 * Set the tracking options.
 * @see http://www.w3.org/TR/geolocation-API/#position-options
 * @param {GeolocationPositionOptions} options PositionOptions as defined by the
- *     HTML5 Geolocation spec at
- *     {@link http://www.w3.org/TR/geolocation-API/#position_options_interface}
+ *     [HTML5 Geolocation spec
+ *     ](http://www.w3.org/TR/geolocation-API/#position_options_interface).
 * @observable
 * @api stable
 */
--- a/src/ol/graticule.js
+++ b/src/ol/graticule.js
@@ -12,6 +12,7 @@ goog.require('ol.style.Stroke');


 /**
+ * Render a grid for a coordinate system on a map.
 * @constructor
 * @param {olx.GraticuleOptions=} opt_options Options.
 * @api
@@ -272,6 +273,7 @@ ol.Graticule.prototype.getInterval_ = function(resolution) {


 /**
+ * Get the map associated with this graticule.
 * @return {ol.Map} The map.
 * @api
 */
@@ -304,6 +306,7 @@ ol.Graticule.prototype.getMeridian_ = function(lon, squaredTolerance, index) {


 /**
+ * Get the list of meridians.  Meridians are lines of equal longitude.
 * @return {Array.<ol.geom.LineString>} The meridians.
 * @api
 */
@@ -336,6 +339,7 @@ ol.Graticule.prototype.getParallel_ = function(lat, squaredTolerance, index) {


 /**
+ * Get the list of parallels.  Pallels are lines of equal latitude.
 * @return {Array.<ol.geom.LineString>} The parallels.
 * @api
 */
@@ -424,6 +428,8 @@ ol.Graticule.prototype.updateProjectionInfo_ = function(projection) {


 /**
+ * Set the map for this graticule.  The graticule will be rendered on the
+ * provided map.
 * @param {ol.Map} map Map.
 * @api
 */
--- a/src/ol/image.js
+++ b/src/ol/image.js
@@ -72,6 +72,7 @@ goog.inherits(ol.Image, ol.ImageBase);


 /**
+ * Get the HTML image element (may be a Canvas, Image, or Video).
 * @param {Object=} opt_context Object.
 * @return {HTMLCanvasElement|Image|HTMLVideoElement} Image.
 * @api
--- a/src/ol/map.js
+++ b/src/ol/map.js
@@ -729,8 +729,10 @@ ol.Map.prototype.getTargetElement = function() {


 /**
- * @param {ol.Pixel} pixel Pixel.
- * @return {ol.Coordinate} Coordinate.
+ * Get the coordinate for a given pixel.  This returns a coordinate in the
+ * map view projection.
+ * @param {ol.Pixel} pixel Pixel position in the map viewport.
+ * @return {ol.Coordinate} The coordinate for the pixel position.
 * @api stable
 */
 ol.Map.prototype.getCoordinateFromPixel = function(pixel) {
@@ -745,6 +747,8 @@ ol.Map.prototype.getCoordinateFromPixel = function(pixel) {


 /**
+ * Get the map controls. Modifying this collection changes the controls
+ * associated with the map.
 * @return {ol.Collection.<ol.control.Control>} Controls.
 * @api stable
 */
@@ -754,6 +758,8 @@ ol.Map.prototype.getControls = function() {


 /**
+ * Get the map overlays. Modifying this collection changes the overlays
+ * associated with the map.
 * @return {ol.Collection.<ol.Overlay>} Overlays.
 * @api stable
 */
@@ -763,8 +769,7 @@ ol.Map.prototype.getOverlays = function() {


 /**
- * Gets the collection of {@link ol.interaction.Interaction} instances
- * associated with this map. Modifying this collection changes the interactions
+ * Get the map interactions. Modifying this collection changes the interactions
 * associated with the map.
 *
 * Interactions are used for e.g. pan, zoom and rotate.
@@ -803,8 +808,10 @@ ol.Map.prototype.getLayers = function() {


 /**
- * @param {ol.Coordinate} coordinate Coordinate.
- * @return {ol.Pixel} Pixel.
+ * Get the pixel for a coordinate.  This takes a coordinate in the map view
+ * projection and returns the corresponding pixel.
+ * @param {ol.Coordinate} coordinate A map coordinate.
+ * @return {ol.Pixel} A pixel position in the map viewport.
 * @api stable
 */
 ol.Map.prototype.getPixelFromCoordinate = function(coordinate) {
@@ -859,6 +866,7 @@ goog.exportProperty(


 /**
+ * Get the element that serves as the map viewport.
 * @return {Element} Viewport.
 * @api stable
 */
@@ -868,10 +876,11 @@ ol.Map.prototype.getViewport = function() {


 /**
- * @return {Element} The map's overlay container. Elements added to this
- * container will let mousedown and touchstart events through to the map, so
- * clicks and gestures on an overlay will trigger {@link ol.MapBrowserEvent}
+ * Get the element that serves as the container for overlays.  Elements added to
+ * this container will let mousedown and touchstart events through to the map,
+ * so clicks and gestures on an overlay will trigger {@link ol.MapBrowserEvent}
 * events.
+ * @return {Element} The map's overlay container.
 */
 ol.Map.prototype.getOverlayContainer = function() {
  return this.overlayContainer_;
@@ -879,10 +888,11 @@ ol.Map.prototype.getOverlayContainer = function() {


 /**
- * @return {Element} The map's overlay container. Elements added to this
- * container won't let mousedown and touchstart events through to the map, so
- * clicks and gestures on an overlay don't trigger any
- * {@link ol.MapBrowserEvent}.
+ * Get the element that serves as a container for overlays that don't allow
+ * event propagation. Elements added to this container won't let mousedown and
+ * touchstart events through to the map, so clicks and gestures on an overlay
+ * don't trigger any {@link ol.MapBrowserEvent}.
+ * @return {Element} The map's overlay container that stops events.
 */
 ol.Map.prototype.getOverlayContainerStopEvent = function() {
  return this.overlayContainerStopEvent_;
@@ -1185,8 +1195,7 @@ ol.Map.prototype.renderSync = function() {


 /**
- * Requests a render frame; rendering will effectively occur at the next browser
- * animation frame.
+ * Request a map rendering (at the next animation frame).
 * @api stable
 */
 ol.Map.prototype.render = function() {
--- a/src/ol/overlay.js
+++ b/src/ol/overlay.js
@@ -51,7 +51,8 @@ ol.OverlayPositioning = {

 /**
 * @classdesc
- * Like {@link ol.control.Control}, Overlays are visible widgets.
+ * An element to be displayed over the map and attached to a single map
+ * location.  Like {@link ol.control.Control}, Overlays are visible widgets.
 * Unlike Controls, they are not in a fixed position on the screen, but are tied
 * to a geographical coordinate, so panning the map will move an Overlay but not
 * a Control.
--- a/src/ol/style/circlestyle.js
+++ b/src/ol/style/circlestyle.js
@@ -124,6 +124,7 @@ ol.style.Circle.prototype.getAnchor = function() {


 /**
+ * Get the fill style for the circle.
 * @return {ol.style.Fill} Fill style.
 * @api
 */
@@ -141,6 +142,7 @@ ol.style.Circle.prototype.getHitDetectionImage = function(pixelRatio) {


 /**
+ * Get the image used to render the circle.
 * @param {number} pixelRatio Pixel ratio.
 * @return {HTMLCanvasElement} Canvas element.
 * @api
@@ -184,6 +186,7 @@ ol.style.Circle.prototype.getOrigin = function() {


 /**
+ * Get the circle radius.
 * @return {number} Radius.
 * @api
 */
@@ -202,6 +205,7 @@ ol.style.Circle.prototype.getSize = function() {


 /**
+ * Get the stroke style for the circle.
 * @return {ol.style.Stroke} Stroke style.
 * @api
 */
--- a/src/ol/style/fillstyle.js
+++ b/src/ol/style/fillstyle.js
@@ -33,6 +33,7 @@ ol.style.Fill = function(opt_options) {


 /**
+ * Get the fill color.
 * @return {ol.Color|string} Color.
 * @api
 */
--- a/src/ol/style/iconstyle.js
+++ b/src/ol/style/iconstyle.js
@@ -243,6 +243,7 @@ ol.style.Icon.prototype.getAnchor = function() {


 /**
+ * Get the image icon.
 * @param {number} pixelRatio Pixel ratio.
 * @return {Image} Image element.
 * @api
@@ -317,6 +318,7 @@ ol.style.Icon.prototype.getOrigin = function() {


 /**
+ * Get the image URL.
 * @return {string|undefined} Image src.
 * @api
 */
--- a/src/ol/style/imagestyle.js
+++ b/src/ol/style/imagestyle.js
@@ -26,7 +26,7 @@ ol.style.ImageOptions;

 /**
 * @classdesc
- * Abstract base class; used for creating subclasses and not instantiated in
+ * A base class used for creating subclasses and not instantiated in
 * apps. Base class for {@link ol.style.Icon} and {@link ol.style.Circle}.
 *
 * @constructor
@@ -69,6 +69,7 @@ ol.style.Image = function(options) {


 /**
+ * Get the symbolizer opacity.
 * @return {number} Opacity.
 * @api
 */
@@ -78,6 +79,7 @@ ol.style.Image.prototype.getOpacity = function() {


 /**
+ * Determine whether the symbolizer rotates with the map.
 * @return {boolean} Rotate with map.
 * @api
 */
@@ -87,6 +89,7 @@ ol.style.Image.prototype.getRotateWithView = function() {


 /**
+ * Get the symoblizer rotation.
 * @return {number} Rotation.
 * @api
 */
@@ -96,6 +99,7 @@ ol.style.Image.prototype.getRotation = function() {


 /**
+ * Get the symbolizer scale.
 * @return {number} Scale.
 * @api
 */
@@ -105,7 +109,8 @@ ol.style.Image.prototype.getScale = function() {


 /**
- * @return {boolean} Snap to pixel?
+ * Determine whether the symbolizer should be snapped to a pixel.
+ * @return {boolean} The symbolizer should snap to a pixel.
 * @api
 */
 ol.style.Image.prototype.getSnapToPixel = function() {
--- a/src/ol/style/regularshapestyle.js
+++ b/src/ol/style/regularshapestyle.js
@@ -149,6 +149,7 @@ ol.style.RegularShape.prototype.getAnchor = function() {


 /**
+ * Get the angle used in generating the shape.
 * @return {number} Shape's rotation in radians.
 * @api
 */
@@ -158,6 +159,7 @@ ol.style.RegularShape.prototype.getAngle = function() {


 /**
+ * Get the fill style for the shape.
 * @return {ol.style.Fill} Fill style.
 * @api
 */
@@ -217,6 +219,7 @@ ol.style.RegularShape.prototype.getOrigin = function() {


 /**
+ * Get the number of points for generating the shape.
 * @return {number} Number of points for stars and regular polygons.
 * @api
 */
@@ -226,6 +229,7 @@ ol.style.RegularShape.prototype.getPoints = function() {


 /**
+ * Get the (primary) radius for the shape.
 * @return {number} Radius.
 * @api
 */
@@ -235,6 +239,7 @@ ol.style.RegularShape.prototype.getRadius = function() {


 /**
+ * Get the secondary radius for the shape.
 * @return {number} Radius2.
 * @api
 */
@@ -253,6 +258,7 @@ ol.style.RegularShape.prototype.getSize = function() {


 /**
+ * Get the stroke style for the shape.
 * @return {ol.style.Stroke} Stroke style.
 * @api
 */
--- a/src/ol/style/strokestyle.js
+++ b/src/ol/style/strokestyle.js
@@ -68,6 +68,7 @@ ol.style.Stroke = function(opt_options) {


 /**
+ * Get the stroke color.
 * @return {ol.Color|string} Color.
 * @api
 */
@@ -77,6 +78,7 @@ ol.style.Stroke.prototype.getColor = function() {


 /**
+ * Get the line cap type for the stroke.
 * @return {string|undefined} Line cap.
 * @api
 */
@@ -86,6 +88,7 @@ ol.style.Stroke.prototype.getLineCap = function() {


 /**
+ * Get the line dash style for the stroke.
 * @return {Array.<number>} Line dash.
 * @api
 */
@@ -95,6 +98,7 @@ ol.style.Stroke.prototype.getLineDash = function() {


 /**
+ * Get the line join type for the stroke.
 * @return {string|undefined} Line join.
 * @api
 */
@@ -104,6 +108,7 @@ ol.style.Stroke.prototype.getLineJoin = function() {


 /**
+ * Get the miter limit for the stroke.
 * @return {number|undefined} Miter limit.
 * @api
 */
@@ -113,6 +118,7 @@ ol.style.Stroke.prototype.getMiterLimit = function() {


 /**
+ * Get the stroke width.
 * @return {number|undefined} Width.
 * @api
 */
--- a/src/ol/style/style.js
+++ b/src/ol/style/style.js
@@ -76,6 +76,7 @@ ol.style.Style = function(opt_options) {


 /**
+ * Get the geometry to be rendered.
 * @return {string|ol.geom.Geometry|ol.style.GeometryFunction}
 * Feature property or geometry or function that returns the geometry that will
 * be rendered with this style.
@@ -87,6 +88,7 @@ ol.style.Style.prototype.getGeometry = function() {


 /**
+ * Get the function used to generate a geometry for rendering.
 * @return {!ol.style.GeometryFunction} Function that is called with a feature
 * and returns the geometry to render instead of the feature's geometry.
 * @api
@@ -97,6 +99,7 @@ ol.style.Style.prototype.getGeometryFunction = function() {


 /**
+ * Get the fill style.
 * @return {ol.style.Fill} Fill style.
 * @api
 */
@@ -106,6 +109,7 @@ ol.style.Style.prototype.getFill = function() {


 /**
+ * Get the image style.
 * @return {ol.style.Image} Image style.
 * @api
 */
@@ -115,6 +119,7 @@ ol.style.Style.prototype.getImage = function() {


 /**
+ * Get the stroke style.
 * @return {ol.style.Stroke} Stroke style.
 * @api
 */
@@ -124,6 +129,7 @@ ol.style.Style.prototype.getStroke = function() {


 /**
+ * Get the text style.
 * @return {ol.style.Text} Text style.
 * @api
 */
@@ -133,6 +139,7 @@ ol.style.Style.prototype.getText = function() {


 /**
+ * Get the z-index for the style.
 * @return {number|undefined} ZIndex.
 * @api
 */
@@ -175,7 +182,7 @@ ol.style.Style.prototype.setGeometry = function(geometry) {


 /**
- * Set the zIndex.
+ * Set the z-index.
 *
 * @param {number|undefined} zIndex ZIndex.
 * @api
--- a/src/ol/style/textstyle.js
+++ b/src/ol/style/textstyle.js
@@ -77,6 +77,7 @@ ol.style.Text = function(opt_options) {


 /**
+ * Get the font name.
 * @return {string|undefined} Font.
 * @api
 */
@@ -86,6 +87,7 @@ ol.style.Text.prototype.getFont = function() {


 /**
+ * Get the x-offset for the text.
 * @return {number} Horizontal text offset.
 * @api
 */
@@ -95,6 +97,7 @@ ol.style.Text.prototype.getOffsetX = function() {


 /**
+ * Get the y-offset for the text.
 * @return {number} Vertical text offset.
 * @api
 */
@@ -104,6 +107,7 @@ ol.style.Text.prototype.getOffsetY = function() {


 /**
+ * Get the fill style for the text.
 * @return {ol.style.Fill} Fill style.
 * @api
 */
@@ -113,6 +117,7 @@ ol.style.Text.prototype.getFill = function() {


 /**
+ * Get the text rotation.
 * @return {number|undefined} Rotation.
 * @api
 */
@@ -122,6 +127,7 @@ ol.style.Text.prototype.getRotation = function() {


 /**
+ * Get the text scale.
 * @return {number|undefined} Scale.
 * @api
 */
@@ -131,6 +137,7 @@ ol.style.Text.prototype.getScale = function() {


 /**
+ * Get the stroke style for the text.
 * @return {ol.style.Stroke} Stroke style.
 * @api
 */
@@ -140,6 +147,7 @@ ol.style.Text.prototype.getStroke = function() {


 /**
+ * Get the text to be rendered.
 * @return {string|undefined} Text.
 * @api
 */
@@ -149,6 +157,7 @@ ol.style.Text.prototype.getText = function() {


 /**
+ * Get the text alignment.
 * @return {string|undefined} Text align.
 * @api
 */
@@ -158,6 +167,7 @@ ol.style.Text.prototype.getTextAlign = function() {


 /**
+ * Get the text baseline.
 * @return {string|undefined} Text baseline.
 * @api
 */
--- a/src/ol/tile.js
+++ b/src/ol/tile.js
@@ -57,6 +57,7 @@ ol.Tile.prototype.changed = function() {


 /**
+ * Get the HTML image element for this tile (may be a Canvas, Image, or Video).
 * @function
 * @param {Object=} opt_context Object.
 * @return {HTMLCanvasElement|HTMLImageElement|HTMLVideoElement} Image.
@@ -73,6 +74,7 @@ ol.Tile.prototype.getKey = function() {


 /**
+ * Get the tile coordinate for this tile.
 * @return {ol.TileCoord}
 * @api
 */
--- a/src/ol/tilegrid/tilegrid.js
+++ b/src/ol/tilegrid/tilegrid.js
@@ -154,6 +154,7 @@ ol.tilegrid.TileGrid.prototype.forEachTileCoordParentTileRange =


 /**
+ * Get the maximum zoom level for the grid.
 * @return {number} Max zoom.
 * @api
 */
@@ -163,6 +164,7 @@ ol.tilegrid.TileGrid.prototype.getMaxZoom = function() {


 /**
+ * Get the minimum zoom level for the grid.
 * @return {number} Min zoom.
 * @api
 */
@@ -172,6 +174,7 @@ ol.tilegrid.TileGrid.prototype.getMinZoom = function() {


 /**
+ * Get the origin for the grid at the given zoom level.
 * @param {number} z Z.
 * @return {ol.Coordinate} Origin.
 * @api stable
@@ -191,6 +194,7 @@ ol.tilegrid.TileGrid.prototype.getOrigin = function(z) {


 /**
+ * Get the resolution for the given zoom level.
 * @param {number} z Z.
 * @return {number} Resolution.
 * @api stable
@@ -204,6 +208,7 @@ ol.tilegrid.TileGrid.prototype.getResolution = function(z) {


 /**
+ * Get the list of resolutions for the tile grid.
 * @return {Array.<number>} Resolutions.
 * @api stable
 */
@@ -368,8 +373,9 @@ ol.tilegrid.TileGrid.prototype.getTileCoordForXYAndResolution_ = function(


 /**
+ * Get a tile coordinate given a map coordinate and zoom level.
 * @param {ol.Coordinate} coordinate Coordinate.
- * @param {number} z Z.
+ * @param {number} z Zoom level.
 * @param {ol.TileCoord=} opt_tileCoord Destination ol.TileCoord object.
 * @return {ol.TileCoord} Tile coordinate.
 * @api
@@ -415,6 +421,7 @@ ol.tilegrid.TileGrid.prototype.getTileRange =


 /**
+ * Get the tile size for a zoom level.
 * @param {number} z Z.
 * @return {number} Tile size.
 * @api stable
--- a/src/ol/tilegrid/wmtstilegrid.js
+++ b/src/ol/tilegrid/wmtstilegrid.js
@@ -56,6 +56,7 @@ ol.tilegrid.WMTS.prototype.getMatrixId = function(z) {


 /**
+ * Get the list of matrix identifiers.
 * @return {Array.<string>} MatrixIds.
 * @api
 */
@@ -65,6 +66,7 @@ ol.tilegrid.WMTS.prototype.getMatrixIds = function() {


 /**
+ * Create a tile grid from a WMTS capabilities matrix set.
 * @param {Object} matrixSet An object representing a matrixSet in the
 *     capabilities document.
 * @return {ol.tilegrid.WMTS} WMTS tileGrid instance.
--- a/src/ol/view.js
+++ b/src/ol/view.js
@@ -243,6 +243,7 @@ ol.View.prototype.constrainRotation = function(rotation, opt_delta) {


 /**
+ * Get the view center.
 * @return {ol.Coordinate|undefined} The center of the view.
 * @observable
 * @api stable
@@ -266,8 +267,8 @@ ol.View.prototype.getHints = function() {


 /**
- * Calculate the extent for the current view state and the passed `size`.
- * `size` is the size in pixels of the box into which the calculated extent
+ * Calculate the extent for the current view state and the passed size.
+ * The size is the pixel dimensions of the box into which the calculated extent
 * should fit. In most cases you want to get the extent of the entire map,
 * that is `map.getSize()`.
 * @param {ol.Size} size Box pixel size.
@@ -288,6 +289,7 @@ ol.View.prototype.calculateExtent = function(size) {


 /**
+ * Get the view projection.
 * @return {ol.proj.Projection} The projection of the view.
 * @api stable
 */
@@ -297,6 +299,7 @@ ol.View.prototype.getProjection = function() {


 /**
+ * Get the view resolution.
 * @return {number|undefined} The resolution of the view.
 * @observable
 * @api stable
@@ -353,6 +356,7 @@ ol.View.prototype.getResolutionForValueFunction = function(opt_power) {


 /**
+ * Get the view rotation.
 * @return {number} The rotation of the view in radians.
 * @observable
 * @api stable
@@ -438,9 +442,9 @@ ol.View.prototype.getZoom = function() {


 /**
- * Fit the map view to the passed `extent` and `size`. `size` is the size in
- * pixels of the box to fit the extent into. In most cases you will want to
- * use the map size, that is `map.getSize()`.
+ * Fit the map view to the passed extent and size. The size is pixel dimensions
+ * of the box to fit the extent into. In most cases you will want to use the map
+ * size, that is `map.getSize()`.
 * @param {ol.Extent} extent Extent.
 * @param {ol.Size} size Box pixel size.
 * @api
@@ -460,8 +464,7 @@ ol.View.prototype.fitExtent = function(extent, size) {


 /**
- * Fit the given geometry based on the given map size and border.
- * Take care on the map angle.
+ * Fit the given geometry into the view based on the given map size and border.
 * @param {ol.geom.SimpleGeometry} geometry Geometry.
 * @param {ol.Size} size Box pixel size.
 * @param {olx.view.FitGeometryOptions=} opt_options Options.
@@ -535,7 +538,6 @@ ol.View.prototype.fitGeometry = function(geometry, size, opt_options) {

 /**
 * Center on coordinate and view position.
- * Take care on the map angle.
 * @param {ol.Coordinate} coordinate Coordinate.
 * @param {ol.Size} size Box pixel size.
 * @param {ol.Pixel} position Position on the view to center on.
--- a/src/ol/webgl/context.js
+++ b/src/ol/webgl/context.js
@@ -191,7 +191,8 @@ ol.webgl.Context.prototype.getCanvas = function() {


 /**
- * @return {WebGLRenderingContext} GL.
+ * Get the WebGL rendering context
+ * @return {WebGLRenderingContext} The rendering context.
 * @api
 */
 ol.webgl.Context.prototype.getGL = function() {
@@ -200,7 +201,8 @@ ol.webgl.Context.prototype.getGL = function() {


 /**
- * @return {WebGLFramebuffer} The framebuffer for the hit-detection.
+ * Get the frame buffer for hit detection.
+ * @return {WebGLFramebuffer} The hit detection frame buffer.
 * @api
 */
 ol.webgl.Context.prototype.getHitDetectionFramebuffer = function() {
@@ -328,9 +330,7 @@ ol.webgl.Context.prototype.initHitDetectionFramebuffer_ = function() {


 /**
- * Just return false if that program is used already. Other use
- * that program (call `gl.useProgram`) and make it the "current
- * program".
+ * Use a program.  If the program is already in use, this will return `false`.
 * @param {WebGLProgram} program Program.
 * @return {boolean} Changed.
 * @api