From c733d7bcff65d7c96c430250f60f26c35546e7c2 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Wed, 1 Aug 2007 23:06:58 +0000 Subject: [PATCH] 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 | 124 ++++++++++++++++++++-------------------- 1 file changed, 63 insertions(+), 61 deletions(-) diff --git a/lib/OpenLayers/Layer.js b/lib/OpenLayers/Layer.js index ebd38df130..0e1f577591 100644 --- a/lib/OpenLayers/Layer.js +++ b/lib/OpenLayers/Layer.js @@ -43,55 +43,54 @@ OpenLayers.Layer = OpenLayers.Class({ /** * APIProperty: map * {} This variable is set when the layer is added to - * the map, via the accessor function setMap(). + * the map, via the accessor function setMap(). */ map: null, /** * APIProperty: isBaseLayer * {Boolean} Whether or not the layer is a base layer. This should be set - * individually by all subclasses. - * Default is false + * individually by all subclasses. 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 - * {Boolean} Whether or not the map's current resolution is within this - * layer's min/max range -- this is set in map's setCenter() - * whenever zoom changes. + * Property: inRange + * {Boolean} The current map resolution is within the layer's min/max range. + * This is set in whenever the zoom changes. */ inRange: false, /** * Propery: imageSize * {} For layers with a gutter, the image is larger than - * the tile by twice the gutter in each dimension. + * the tile by twice the gutter in each dimension. */ imageSize: null, /** * Property: imageOffset * {} For layers with a gutter, the image offset - * represents displacement due to the gutter. + * represents displacement due to the gutter. */ imageOffset: null, @@ -100,57 +99,64 @@ OpenLayers.Layer = OpenLayers.Class({ /** * Property: options * {Object} An optional object whose properties will be set on the layer. - * Any of the layer properties can be set as a property of the options - * object and sent to the constructor when the layer is created. + * Any of the layer properties can be set as a property of the options + * object and sent to the constructor when the layer is created. */ options: null, /** * APIProperty: gutter * {Integer} Determines the width (in pixels) of the gutter around image - * tiles to ignore. By setting this property to a non-zero - * value, images will be requested that are wider and taller - * than the tile size by a value of 2 x gutter. This allows - * artifacts of rendering at tile edges to be ignored. Set a - * gutter value that is equal to half the size of the widest - * symbol that needs to be displayed. Defaults to zero. - * Non-tiled layers always have zero gutter. + * tiles to ignore. By setting this property to a non-zero value, + * images will be requested that are wider and taller than the tile + * size by a value of 2 x gutter. This allows artifacts of rendering + * at tile edges to be ignored. Set a gutter value that is equal to + * half the size of the widest symbol that needs to be displayed. + * Defaults to zero. 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 - * units if appropriate. + * string this layer - also set maxExtent, maxResolution, and units if + * appropriate. */ projection: null, /** * APIProperty: units * {String} The layer map units. Defaults to 'degrees'. Possible values - * are 'degrees' (or 'dd'), 'm', 'ft', 'km', 'mi', 'inches'. + * are 'degrees' (or 'dd'), 'm', 'ft', 'km', 'mi', 'inches'. */ units: null, /** * 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 instead wherever possible. */ scales: null, /** * 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, - * maxScale, etc.). + * order. If this is not set in the layer constructor, it will be set + * based on other resolution related properties (maxExtent, + * maxResolution, maxScale, etc.). */ resolutions: null, /** * APIProperty: maxExtent - * {} + * {} The center of these bounds will not stray outside + * of the viewport extent during panning. In addition, if + * is set to false, data will not be + * requested that falls completely outside of these bounds. */ maxExtent: null, @@ -163,9 +169,9 @@ OpenLayers.Layer = OpenLayers.Class({ /** * APIProperty: maxResolution * {Float} Default max is 360 deg / 256 px, which corresponds to - * zoom level 0 on gmaps. Specify a different value in the layer - * options if you are not using a geographic projection and - * displaying the whole world. + * zoom level 0 on gmaps. Specify a different value in the layer + * options if you are not using a geographic projection and + * displaying the whole world. */ maxResolution: 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 - * this has been removed? - * Default is true. + * setNewBaseLayer - {Boolean} Set a new base layer when this layer has + * been destroyed. 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 - * a changelayer event on the map. + * Sets the new layer name for this layer. Can trigger a changelayer event + * on the map. * * Parameters: * newName - {String} The new name. @@ -365,8 +370,8 @@ OpenLayers.Layer = OpenLayers.Class({ * * Parameters: * bound - {} - * zoomChanged - {Boolean} Tells when zoom has changed, as layers - * have to do some init work in that case. + * zoomChanged - {Boolean} Tells when zoom has changed, as layers have to + * do some init work in that case. * dragging - {Boolean} */ moveTo:function(bounds, zoomChanged, dragging) { @@ -418,7 +423,7 @@ OpenLayers.Layer = OpenLayers.Class({ * * Return: * {} The size that the image should be, taking into - * account gutters. + * account gutters. */ getImageSize: function() { return (this.imageSize || this.tileSize); @@ -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; @@ -462,10 +467,10 @@ OpenLayers.Layer = OpenLayers.Class({ /** * APIMethod: setVisibility - * Set the visibility flag for the layer and hide/show&redraw accordingly. + * Set the visibility flag for the layer and hide/show & redraw accordingly. * Fire event unless otherwise specified * - * Note that visibility is no longer simply whether or not the layer's + * Note that visibility is no longer simply whether or not the layer's * style.display is set to "block". Now we store a 'visibility' state * property on the layer class, this allows us to remember whether or * not we *desire* for a layer to be visible. In the case where the @@ -505,8 +510,8 @@ OpenLayers.Layer = OpenLayers.Class({ * Method: calculateInRange * * Return: - * {Boolean} Whether or not the layer is displayable at the current map's - * current resolution + * {Boolean} The layer is displayable at the current map's current + * resolution. */ calculateInRange: function() { var inRange = false; @@ -546,11 +551,10 @@ OpenLayers.Layer = OpenLayers.Class({ * between the zoom levels of the map and the resolution display * of the layer. * - * The user has several options that determine how the array is set up. + * The user has several options that determine how the array is set up. * - * For a detailed explanation, see the following wiki from the + * For a detailed explanation, see the following wiki from the * openlayers.org homepage: - * * http://trac.openlayers.org/wiki/SettingZoomLevels */ initResolutions: function() { @@ -677,7 +681,7 @@ OpenLayers.Layer = OpenLayers.Class({ * * Return: * {Float} The currently selected resolution of the map, taken from the - * resolutions array, indexed by current zoom level. + * resolutions array, indexed by current zoom level. */ getResolution: function() { var zoom = this.map.getZoom(); @@ -689,7 +693,7 @@ OpenLayers.Layer = OpenLayers.Class({ * * Return: * {} A Bounds object which represents the lon/lat - * bounds of the current viewPort. + * bounds of the current viewPort. */ getExtent: function() { // just use stock map calculateBounds function -- passing no arguments @@ -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 - * calculating the ideal resolution for the given exteng (based - * on the map size) and then find the smallest resolution that - * is greater than this ideal resolution. + * that still contains the passed-in extent. We do this by calculating + * the ideal resolution for the given exteng (based on the map size) + * and then find the smallest resolution that is greater than this + * 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 - * passed-in resolution. + * that is the smallest resolution that is greater than the passed-in + * resolution. */ getZoomForResolution: function(resolution) { @@ -748,8 +752,7 @@ OpenLayers.Layer = OpenLayers.Class({ * * Return: * {} An OpenLayers.LonLat which is the passed-in - * view port , translated into - * lon/lat by the layer + * view port , translated into lon/lat by the layer. */ getLonLatFromViewPortPx: function (viewPortPx) { var lonlat = null; @@ -781,8 +784,7 @@ OpenLayers.Layer = OpenLayers.Class({ * * Return: * {} An which is the passed-in - * ,translated into view - * port pixels. + * ,translated into view port pixels. */ getViewPortPxFromLonLat: function (lonlat) { var px = null;