coding standards and a few improved doc comments

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

lib/OpenLayers/Layer.js

@@ -50,34 +50,33 @@ OpenLayers.Layer = OpenLayers.Class({
     /**
      * APIProperty: isBaseLayer
      * {Boolean} Whether or not the layer is a base layer. This should be set 
-     *           individually by all subclasses. 
+     *     individually by all subclasses. Default is false
-     *           Default is false
      */
     isBaseLayer: false,
  
     /**
      * Property: alpha
-     * {Boolean} Whether or not the layer's images have an alpha channel 
+     * {Boolean} The layer's images have an alpha channel.  Default is false. 
      */
     alpha: false,
 
     /** 
      * APIProperty: displayInLayerSwitcher
-     * {Boolean} Should the layer's name appear in the layer switcher?
+     * {Boolean} Display the layer's name in the layer switcher.  Default is
+     *     true.
      */
     displayInLayerSwitcher: true,
 
     /**
      * APIProperty: visibility
-     * {Boolean} Whether or not the layer should be displayed in the map
+     * {Boolean} The layer should be displayed in the map.  Default is true.
      */
     visibility: true,
 
     /** 
-     * APIProperty: inRange
+     * Property: inRange
-     * {Boolean} Whether or not the map's current resolution is within this 
+     * {Boolean} The current map resolution is within the layer's min/max range.
-     *           layer's min/max range -- this is set in map's setCenter() 
+     *     This is set in <OpenLayers.Map.setCenter> whenever the zoom changes.
-     *           whenever zoom changes.
      */
     inRange: false,
     
@@ -108,21 +107,20 @@ OpenLayers.Layer = OpenLayers.Class({
     /**
      * APIProperty: gutter
      * {Integer} Determines the width (in pixels) of the gutter around image
-     *           tiles to ignore.  By setting this property to a non-zero 
+     *     tiles to ignore.  By setting this property to a non-zero value,
-     *           value, images will be requested that are wider and taller 
+     *     images will be requested that are wider and taller than the tile
-     *           than the tile size by a value of 2 x gutter.  This allows 
+     *     size by a value of 2 x gutter.  This allows artifacts of rendering
-     *           artifacts of rendering at tile edges to be ignored.  Set a 
+     *     at tile edges to be ignored.  Set a gutter value that is equal to
-     *           gutter value that is equal to half the size of the widest 
+     *     half the size of the widest symbol that needs to be displayed.
-     *           symbol that needs to be displayed.  Defaults to zero.
+     *     Defaults to zero.  Non-tiled layers always have zero gutter.
-     *           Non-tiled layers always have zero gutter.
      */ 
     gutter: 0, 
 
     /**
      * APIProperty: projection
      * {String} Set in the layer options to override the default projection
-     *          string this layer - also set maxExtent, maxResolution, and 
+     *     string this layer - also set maxExtent, maxResolution, and units if
-     *          units if appropriate.
+     *     appropriate.
      */
     projection: null,    
     
@@ -135,7 +133,12 @@ OpenLayers.Layer = OpenLayers.Class({
 
     /**
      * APIProperty: scales
-     * {Array}
+     * {Array}  An array of map scales in descending order.  The values in the
+     *     array correspond to the map scale denominator.  Note that these
+     *     values only make sense if the display (monitor) resolution of the
+     *     client is correctly guessed by whomever is configuring the
+     *     application.  In addition, the units property must also be set.
+     *     Use <resolutions> instead wherever possible.
      */
     scales: null,
 
@@ -143,14 +146,17 @@ OpenLayers.Layer = OpenLayers.Class({
      * APIProperty: resolutions
      * {Array} A list of map resolutions (map units per pixel) in descending
      *     order.  If this is not set in the layer constructor, it will be set
-     * based on other resolution related properties (maxExtent, maxResolution,
+     *     based on other resolution related properties (maxExtent,
-     * maxScale, etc.).
+     *     maxResolution, maxScale, etc.).
      */
     resolutions: null,
     
     /**
      * APIProperty: maxExtent
-     * {<OpenLayers.Bounds>}
+     * {<OpenLayers.Bounds>}  The center of these bounds will not stray outside
+     *     of the viewport extent during panning.  In addition, if
+     *     <displayOutsideMaxExtent> is set to false, data will not be
+     *     requested that falls completely outside of these bounds.
      */
     maxExtent: null,
     
@@ -196,7 +202,7 @@ OpenLayers.Layer = OpenLayers.Class({
     /**
      * APIProperty: displayOutsideMaxExtent
      * {Boolean} Request map tiles that are completely outside of the max extent
-     *           for this layer.  Defaults to false
+     *     for this layer.  Defaults to false.
      */
     displayOutsideMaxExtent: false,
 
@@ -244,9 +250,8 @@ OpenLayers.Layer = OpenLayers.Class({
      *     the Javascript garbage cleaner can not take care of on its own.
      *
      * Parameters:
-     * setNewBaseLayer - {Boolean} Should a new baselayer be selected when
+     * setNewBaseLayer - {Boolean} Set a new base layer when this layer has
-     *                             this has been removed? 
+     *     been destroyed.  Default is true.
-     *                             Default is true.
      */
     destroy: function(setNewBaseLayer) {
         if (setNewBaseLayer == null) {
@@ -293,8 +298,8 @@ OpenLayers.Layer = OpenLayers.Class({
     
     /** 
      * APIMethod: setName
-     * Sets the new layer name for this layer.  Can trigger
+     * Sets the new layer name for this layer.  Can trigger a changelayer event
-     * a changelayer event on the map.
+     *     on the map.
      *
      * Parameters:
      * newName - {String} The new name.
@@ -365,8 +370,8 @@ OpenLayers.Layer = OpenLayers.Class({
      * 
      * Parameters:
      * bound - {<OpenLayers.Bounds>}
-     * zoomChanged - {Boolean} Tells when zoom has changed, as layers 
+     * zoomChanged - {Boolean} Tells when zoom has changed, as layers have to
-     *                         have to do some init work in that case.
+     *     do some init work in that case.
      * dragging - {Boolean}
      */
     moveTo:function(bounds, zoomChanged, dragging) {
@@ -454,7 +459,7 @@ OpenLayers.Layer = OpenLayers.Class({
      * APIMethod: getVisibility
      * 
      * Return:
-     * {Boolean} Whether or not the layer should be displayed (if in range)
+     * {Boolean} The layer should be displayed (if in range).
      */
     getVisibility: function() {
         return this.visibility;
@@ -505,8 +510,8 @@ OpenLayers.Layer = OpenLayers.Class({
      * Method: calculateInRange
      * 
      * Return:
-     * {Boolean} Whether or not the layer is displayable at the current map's
+     * {Boolean} The layer is displayable at the current map's current
-     *           current resolution
+     *     resolution.
      */
     calculateInRange: function() {
         var inRange = false;
@@ -550,7 +555,6 @@ OpenLayers.Layer = OpenLayers.Class({
      *  
      * For a detailed explanation, see the following wiki from the 
      *     openlayers.org homepage:
-     * 
      *     http://trac.openlayers.org/wiki/SettingZoomLevels
      */
     initResolutions: function() {
@@ -706,10 +710,10 @@ OpenLayers.Layer = OpenLayers.Class({
      *
      * Return:
      * {Integer} The index of the zoomLevel (entry in the resolutions array) 
-     *           that still contains the passed-in extent. We do this by 
+     *     that still contains the passed-in extent. We do this by calculating
-     *           calculating the ideal resolution for the given exteng (based
+     *     the ideal resolution for the given exteng (based on the map size)
-     *           on the map size) and then find the smallest resolution that 
+     *     and then find the smallest resolution that is greater than this
-     *           is greater than this ideal resolution.
+     *     ideal resolution.
      */
     getZoomForExtent: function(extent) {
         var viewSize = this.map.getSize();
@@ -727,8 +731,8 @@ OpenLayers.Layer = OpenLayers.Class({
      * 
      * Return:
      * {Integer} The index of the zoomLevel (entry in the resolutions array) 
-     *           that is the smallest resolution that is greater than the 
+     *     that is the smallest resolution that is greater than the passed-in
-     *           passed-in resolution.
+     *     resolution.
      */
     getZoomForResolution: function(resolution) {
         
@@ -748,8 +752,7 @@ OpenLayers.Layer = OpenLayers.Class({
      *
      * Return:
      * {<OpenLayers.LonLat>} An OpenLayers.LonLat which is the passed-in 
-     *                       view port <OpenLayers.Pixel>, translated into 
+     *     view port <OpenLayers.Pixel>, translated into lon/lat by the layer.
-     *                       lon/lat by the layer
      */
     getLonLatFromViewPortPx: function (viewPortPx) {
         var lonlat = null;
@@ -781,8 +784,7 @@ OpenLayers.Layer = OpenLayers.Class({
      *
      * Return: 
      * {<OpenLayers.Pixel>} An <OpenLayers.Pixel> which is the passed-in 
-     *                      <OpenLayers.LonLat>,translated into view 
+     *     <OpenLayers.LonLat>,translated into view port pixels.
-     *                      port pixels.
      */
     getViewPortPxFromLonLat: function (lonlat) {
         var px = null;