Commit documentation changes from gstamp, patch from #869.

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

lib/OpenLayers/BaseTypes.js

@@ -19,7 +19,7 @@
  * Whether or not a string starts with another string. 
  * 
  * Parameters:
- * sStart - {Sring}
+ * sStart - {Sring} The string we're testing for.
  *  
  * Return:
  * {Boolean} Whether or not this string starts with the string passed in.
@@ -33,7 +33,7 @@ String.prototype.startsWith = function(sStart) {
  * Whether or not a string contains another string.
  * 
  * Parameters:
- * str - {String}
+ * str - {String} The string that we're testing for.
  * 
  * Return:
  * {Boolean} Whether or not this string contains with the string passed in.
@@ -143,12 +143,14 @@ Number.prototype.limitSigDigs = function(sig) {
 /**
  * APIMethod: Function.bind
  * Bind a function to an object. 
+ * Method to easily create closures with 'this' altered.
  * 
  * Parameters:
- * object - {Object}
+ * object - {Object} the this parameter
  * 
  * Return:
- * {Function}
+ * {Function} A closure with 'this' altered to the first
+ *            argument.
  */
 Function.prototype.bind = function() {
     var __method = this;
@@ -173,7 +175,7 @@ Function.prototype.bind = function() {
  *     as first parameter when called. 
  * 
  * Parameters:
- * object - {Object}
+ * object - {Object} A reference to this.
  * 
  * Return:
  * {Function}
@@ -183,4 +185,4 @@ Function.prototype.bindAsEventListener = function(object) {
     return function(event) {
         return __method.call(object, event || window.event);
     };
-};
+};

lib/OpenLayers/Layer.js

@@ -293,9 +293,11 @@ OpenLayers.Layer = OpenLayers.Class({
     
     /** 
      * APIMethod: setName
-     * 
+     * Sets the new layer name for this layer.  Can trigger
+     * a changelayer event on the map.
+     *
      * Parameters:
-     * newName - {String}
+     * newName - {String} The new name.
      */
     setName: function(newName) {
         if (newName != this.name) {

lib/OpenLayers/Util.js

@@ -127,14 +127,19 @@ OpenLayers.Util.indexOf = function(array, obj) {
 /**
  * Function: modifyDOMElement
  * 
+ * Modifies many properties of a DOM element all at once.  Passing in 
+ * null to an individual parameter will avoid setting the attribute.
+ *
  * Parameters:
- * id - {String}
- * px - {<OpenLayers.Pixel>}
- * sz - {<OpenLayers.Size>}
- * position - {String}
- * border - {String}
- * overflow - {String}
- * opacity - {Float} Fractional value (0.0 - 1.0)
+ * id - {String} The element id attribute to set.
+ * px - {<OpenLayers.Pixel>} The left and top style position.
+ * sz - {<OpenLayers.Size>}  The width and height style attributes.
+ * position - {String}       The position attribute.  eg: absolute, 
+ *                           relative, etc.
+ * border - {String}         The style.border attribute.  eg:
+ *                           solid black 2px
+ * overflow - {String}       The style.overview attribute.  
+ * opacity - {Float}         Fractional value (0.0 - 1.0)
  */
 OpenLayers.Util.modifyDOMElement = function(element, id, px, sz, position, 
                                             border, overflow, opacity) {
@@ -167,17 +172,25 @@ OpenLayers.Util.modifyDOMElement = function(element, id, px, sz, position,
 
 /** 
  * Function: createDiv
+ * Creates a new div and optionally set some standard attributes.
+ * Null may be passed to each parameter if you do not wish to
+ * set a particular attribute.d
  * 
  * Note: zIndex is NOT set
  * 
  * Parameters:
- * id - {String}
- * px - {<OpenLayers.Pixel>}
- * sz - {<OpenLayers.Size>}
- * imgURL - {String}
- * position - {String}
- * border - {String}
- * overflow - {String}
+ * id - {String} An identifier for this element.  If no id is
+ *               passed an identifier will be created 
+ *               automatically.
+ * px - {<OpenLayers.Pixel>} The element left and top position. 
+ * sz - {<OpenLayers.Size>} The element width and height.
+ * imgURL - {String} A url pointing to an image to use as a 
+ *                   background image.
+ * position - {String} The style.position value. eg: absolute,
+ *                     relative etc.
+ * border - {String} The the style.border value. 
+ *                   eg: 2px solid black
+ * overflow - {String} The style.overflow value. Eg. hidden
  * opacity - {Float} Fractional value (0.0 - 1.0)
  * 
  * Return: 
@@ -207,15 +220,18 @@ OpenLayers.Util.createDiv = function(id, px, sz, imgURL, position,
 
 /**
  * Function: createImage
+ * Creates an img element with specific attribute values.
  *  
  * Parameters:
- * id - {String}
- * px - {<OpenLayers.Pixel>}
- * sz - {<OpenLayers.Size>}
- * imgURL - {String}
- * position - {String}
- * border - {String}
- * delayDisplay - {Boolean}
+ * id - {String} The id field for the img.  If none assigned one will be
+ *               automatically generated.
+ * px - {<OpenLayers.Pixel>} The left and top positions.
+ * sz - {<OpenLayers.Size>} The style.width and style.height values.
+ * imgURL - {String} The url to use as the image source.
+ * position - {String} The style.position value.
+ * border - {String} The border to place around the image.
+ * delayDisplay - {Boolean} If true waits until the image has been
+ *                          loaded.
  * opacity - {Float} Fractional value (0.0 - 1.0)
  * 
  * Return:
@@ -333,9 +349,12 @@ OpenLayers.Util.onImageLoadError = function() {
 
 /**
  * Function: alphaHack
+ * Checks whether it's necessary (and possible) to use the png alpha
+ * hack which allows alpha transparency for png images under Internet
+ * Explorer.
  * 
  * Return:
- * {Boolean}
+ * {Boolean} true if alpha has is necessary and possible, false otherwise.
  */
 OpenLayers.Util.alphaHack = function() {
     var arVersion = navigator.appVersion.split("MSIE");
@@ -804,7 +823,7 @@ OpenLayers.Util.lastSeqID = 0;
  * Function: createUniqueID
  * 
  * Parameters:
- * prefix {String} String to prefix random id. 
+ * prefix {String} String to prefix unique id. 
  *                 If null, default is "id_"
  * 
  * Return:
@@ -843,7 +862,7 @@ OpenLayers.DOTS_PER_INCH = 72;
  * Function: normalzeScale
  * 
  * Parameters:
- * scale {float}
+ * scale - {float}
  * 
  * Return:
  * {Float} A normalized scale value, in 1 / X format. 
@@ -925,7 +944,8 @@ OpenLayers.Util.safeStopPropagation = function(evt) {
 
 /**
  * Function: pagePositon
- * 
+ * Calculates the position of an element on the page. 
+ *
  * Parameters:
  * forElement - {DOMElement}
  * 
@@ -1045,7 +1065,10 @@ OpenLayers.Util.isEquivalentUrl = function(url1, url2, options) {
  * 
  * Parameters:
  * url - {String}
- * options - {Object}
+ * options - {Object} A hash of options.  Can be one of:
+ *            ignoreCase: lowercase url,
+ *            ignorePort80: don't include explicit port if port is 80,
+ *            ignoreHash: Don't include part of url after the hash (#).
  * 
  * Return:
  * {Object} An object with separate url, a, port, host, and args parsed out 
@@ -1153,9 +1176,10 @@ OpenLayers.Util.createUrlObject = function(url, options) {
  
 /**
  * Function: removeTail
+ * Takes a url and removes everything after the ? and #
  * 
  * Parameters:
- * url - {String}
+ * url - {String} The url to process
  * 
  * Return:
  * {String} The string with all queryString and Hash removed