Extent docs

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