doc tweaks for Bounds (see #983).

git-svn-id: http://svn.openlayers.org/trunk/openlayers@4351 dc9f47b5-9b13-0410-9fdd-eb0c1a62fdaf

lib/OpenLayers/BaseTypes/Bounds.js

@@ -7,12 +7,12 @@
  * Instances of this class represent bounding boxes.  Data stored as left,
  * bottom, right, top floats. All values are initialized to null, however,
  * you should make sure you set them before using the bounds for anything.
- * Possible use case:
  * 
+ * Possible use case:
  * > bounds = new OpenLayers.Bounds();
  * > bounds.extend(new OpenLayers.LonLat(4,5));
  * > bounds.extend(new OpenLayers.LonLat(5,6));
- * > bounds.toBBOX() // returns 4,5,5,6
+ * > bounds.toBBOX(); // returns 4,5,5,6
  */
 OpenLayers.Bounds = OpenLayers.Class({
 
@@ -81,13 +81,13 @@ OpenLayers.Bounds = OpenLayers.Class({
 
     /**
      * Method: equals
-     * Test a two bounds for equivalence
+     * Test a two bounds for equivalence.
      *
      * Parameters:
      * bounds - {<OpenLayers.Bounds>}
      *
      * Returns:
-     * {Boolean} The passed-in OpenLayers.Bounds object has the same left,
+     * {Boolean} The passed-in bounds object has the same left,
      *           right, top, bottom components as this.  Note that if bounds 
      *           passed in is null, returns false.
      */
@@ -106,7 +106,7 @@ OpenLayers.Bounds = OpenLayers.Class({
      * APIMethod: toString
      * 
      * Returns:
-     * {String} String representation of OpenLayers.Bounds object. 
+     * {String} String representation of bounds object. 
      *          (ex.<i>"left-bottom=(5,42) right-top=(10,45)"</i>)
      */
     toString:function() {
@@ -132,7 +132,7 @@ OpenLayers.Bounds = OpenLayers.Class({
      *                     Default is 6
      * 
      * Returns:
-     * {String} Simple String representation of OpenLayers.Bounds object.
+     * {String} Simple String representation of bounds object.
      *          (ex. <i>"5,42,10,45"</i>)
      */
     toBBOX:function(decimal) {
@@ -162,7 +162,7 @@ OpenLayers.Bounds = OpenLayers.Class({
      * APIMethod: getHeight
      * 
      * Returns:
-     * {Float} The height of the bounds
+     * {Float} The height of the bounds (top minus bottom).
      */
     getHeight:function() {
         return (this.top - this.bottom);
@@ -172,7 +172,7 @@ OpenLayers.Bounds = OpenLayers.Class({
      * APIMethod: getSize
      * 
      * Returns:
-     * {<OpenLayers.Size>} An <OpenLayers.Size> which represents the size of the box
+     * {<OpenLayers.Size>} The size of the box.
      */
     getSize:function() {
         return new OpenLayers.Size(this.getWidth(), this.getHeight());
@@ -182,8 +182,7 @@ OpenLayers.Bounds = OpenLayers.Class({
      * APIMethod: getCenterPixel
      * 
      * Returns:
-     * {<OpenLayers.Pixel>} An <OpenLayers.Pixel> which represents the center 
+     * {<OpenLayers.Pixel>} The center of the bounds in pixel space.
-     *                      of the bounds
      */
     getCenterPixel:function() {
         return new OpenLayers.Pixel( (this.left + this.right) / 2,
@@ -194,8 +193,7 @@ OpenLayers.Bounds = OpenLayers.Class({
      * APIMethod: getCenterLonLat
      * 
      * Returns:
-     * {<OpenLayers.LonLat>} An <OpenLayers.LonLat> which represents the center 
+     * {<OpenLayers.LonLat>} The center of the bounds in map space.
-     *                      of the bounds
      */
     getCenterLonLat:function() {
         return new OpenLayers.LonLat( (this.left + this.right) / 2,
@@ -210,9 +208,8 @@ OpenLayers.Bounds = OpenLayers.Class({
      * y - {Float}
      * 
      * Returns:
-     * {<OpenLayers.Bounds>} A new <OpenLayers.Bounds> whose coordinates are 
+     * {<OpenLayers.Bounds>} A new bounds whose coordinates are the same as
-     *                       the same as this, but shifted by the passed-in 
+     *     this, but shifted by the passed-in x and y values.
-     *                       x and y values
      */
     add:function(x, y) {
         if ( (x == null) || (y == null) ) {
@@ -227,8 +224,7 @@ OpenLayers.Bounds = OpenLayers.Class({
     /**
      * APIMethod: extend
      * Extend the bounds to include the point, lonlat, or bounds specified.
-     * Note: This function assumes that left<right and bottom<top.
+     *     Note, this function assumes that left < right and bottom < top.
-     * 
      * 
      * Parameters: 
      * object - {Object} Can be LonLat, Point, or Bounds
@@ -274,10 +270,10 @@ OpenLayers.Bounds = OpenLayers.Class({
      * Parameters:
      * ll - {<OpenLayers.LonLat>}
      * inclusive - {Boolean} Whether or not to include the border.
-     *                       Default is true.
+     *     Default is true.
      *
      * Returns:
-     * {Boolean} Whether or not the passed-in lonlat is within this bounds.
+     * {Boolean} The passed-in lonlat is within this bounds.
      */
     containsLonLat:function(ll, inclusive) {
         return this.contains(ll.lon, ll.lat, inclusive);
@@ -288,11 +284,11 @@ OpenLayers.Bounds = OpenLayers.Class({
      * 
      * Parameters:
      * px - {<OpenLayers.Pixel>}
-     * inclusive - {Boolean} Whether or not to include the border. 
+     * inclusive - {Boolean} Whether or not to include the border. Default is
-     *                       Default is true.
+     *     true.
      *
      * Returns:
-     * {Boolean} Whether or not the passed-in pixel is within this bounds.
+     * {Boolean} The passed-in pixel is within this bounds.
      */
     containsPixel:function(px, inclusive) {
         return this.contains(px.x, px.y, inclusive);
@@ -304,12 +300,12 @@ OpenLayers.Bounds = OpenLayers.Class({
      * Parameters:
      * x - {Float}
      * y - {Float}
-     * inclusive - {Boolean} Whether or not to include the border. 
+     * inclusive - {Boolean} Whether or not to include the border. Default is
-     *                       Default is true.
+     *     true.
      *
      * Returns:
      * {Boolean} Whether or not the passed-in coordinates are within this
-     *           bounds.
+     *     bounds.
      */
     contains:function(x, y, inclusive) {
     
@@ -334,13 +330,13 @@ OpenLayers.Bounds = OpenLayers.Class({
      * 
      * Parameters:
      * bounds - {<OpenLayers.Bounds>}
-     * inclusive - {<Boolean>} Whether or not to include the border. 
+     * inclusive - {<Boolean>} Whether or not to include the border.  Default
-     *                         Default is true.
+     *     is true.
      *
      * Returns:
-     * {Boolean} Whether or not the passed-in OpenLayers.Bounds object 
+     * {Boolean} The passed-in OpenLayers.Bounds object intersects this bounds.
-     *           intersects this bounds. Simple math just check if either 
+     *     Simple math just check if either contains the other, allowing for
-     *           contains the other, allowing for partial.
+     *     partial.
      */
     intersectsBounds:function(bounds, inclusive) {
 
@@ -369,16 +365,14 @@ OpenLayers.Bounds = OpenLayers.Class({
      * APIMethod: containsBounds
      * 
      * bounds - {<OpenLayers.Bounds>}
-     * partial - {<Boolean>} If true, only part of passed-in 
+     * partial - {<Boolean>} If true, only part of passed-in bounds needs be
-     *                       <OpenLayers.Bounds> needs be within this bounds. 
+     *     within this bounds.  If false, the entire passed-in bounds must be
-     *                       If false, the entire passed-in bounds must be
+     *     within. Default is false
-     *                       within. Default is false
+     * inclusive - {<Boolean>} Whether or not to include the border. Default is
-     * inclusive - {<Boolean>} Whether or not to include the border. 
+     *     true.
-     *                         Default is true.
      *
      * Returns:
-     * {Boolean} Whether or not the passed-in OpenLayers.Bounds object is 
+     * {Boolean} The passed-in bounds object is contained within this bounds. 
-     *           contained within this bounds. 
      */
     containsBounds:function(bounds, partial, inclusive) {
 
@@ -418,8 +412,8 @@ OpenLayers.Bounds = OpenLayers.Class({
      * lonlat - {<OpenLayers.LonLat>}
      * 
      * Returns:
-     * {String} The quadrant ("br" "tr" "tl" "bl") of the bounds in which 
+     * {String} The quadrant ("br" "tr" "tl" "bl") of the bounds in which the
-     *          the coordinate lies.
+     *     coordinate lies.
      */
     determineQuadrant: function(lonlat) {
     
@@ -495,7 +489,7 @@ OpenLayers.Bounds = OpenLayers.Class({
  * str - {String}Comma-separated bounds string. (ex. <i>"5,42,10,45"</i>)
  * 
  * Returns:
- * {<OpenLayers.Bounds>} New <OpenLayers.Bounds> object built from the 
+ * {<OpenLayers.Bounds>} New bounds object built from the 
  *                       passed-in String.
  */
 OpenLayers.Bounds.fromString = function(str) {
@@ -512,8 +506,7 @@ OpenLayers.Bounds.fromString = function(str) {
  * bbox - {Array(Float)} Array of bounds values (ex. <i>[5,42,10,45]</i>)
  *
  * Returns:
- * {<OpenLayers.Bounds>} New <OpenLayers.Bounds> object built from the 
+ * {<OpenLayers.Bounds>} New bounds object built from the passed-in Array.
- *                       passed-in Array.
  */
 OpenLayers.Bounds.fromArray = function(bbox) {
     return new OpenLayers.Bounds(parseFloat(bbox[0]),
@@ -531,8 +524,7 @@ OpenLayers.Bounds.fromArray = function(bbox) {
  * size - {<OpenLayers.Size>} 
  *
  * Returns:
- * {<OpenLayers.Bounds>} New <OpenLayers.Bounds> object built from the 
+ * {<OpenLayers.Bounds>} New bounds object built from the passed-in size.
- *                       passed-in size.
  */
 OpenLayers.Bounds.fromSize = function(size) {
     return new OpenLayers.Bounds(0,