Documentation enhancements. No functional change.

lib/OpenLayers/Control/MousePosition.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2006-2012 by OpenLayers Contributors (see authors.txt for 
+/* Copyright (c) 2006-2012 by OpenLayers Contributors (see authors.txt for
  * full list of contributors). Published under the 2-clause BSD license.
  * See license.txt in the OpenLayers distribution or repository for the
  * full text of the license. */
@@ -13,11 +13,23 @@
  * The MousePosition control displays geographic coordinates of the mouse
  * pointer, as it is moved about the map.
  *
+ * You can use the <prefix>- or <suffix>-properties to provide more information
+ * about the displayed coordinates to the user:
+ *
+ * (code)
+ *     var mousePositionCtrl = new OpenLayers.Control.MousePosition({
+ *         prefix: '<a target="_blank" ' +
+ *             'href="http://spatialreference.org/ref/epsg/4326/">' +
+ *             'EPSG:4326</a> coordinates: '
+ *         }
+ *     );
+ * (end code)
+ *
  * Inherits from:
  *  - <OpenLayers.Control>
  */
 OpenLayers.Control.MousePosition = OpenLayers.Class(OpenLayers.Control, {
-    
+
     /**
      * APIProperty: autoActivate
      * {Boolean} Activate the control when it is added to a map.  Default is
@@ -25,50 +37,55 @@ OpenLayers.Control.MousePosition = OpenLayers.Class(OpenLayers.Control, {
      */
     autoActivate: true,
 
-    /** 
+    /**
      * Property: element
-     * {DOMElement} 
+     * {DOMElement}
      */
     element: null,
-    
+
-    /** 
+    /**
      * APIProperty: prefix
-     * {String}
+     * {String} A string to be prepended to the current pointers coordinates
+     *     when it is rendered.  Defaults to the empty string ''.
      */
     prefix: '',
-    
+
-    /** 
+    /**
      * APIProperty: separator
-     * {String}
+     * {String} A string to be used to seperate the two coordinates from each
+     *     other.  Defaults to the string ', ', which will result in a
+     *     rendered coordinate of e.g. '42.12, 21.22'.
      */
     separator: ', ',
-    
+
-    /** 
+    /**
      * APIProperty: suffix
-     * {String}
+     * {String} A string to be appended to the current pointers coordinates
+     *     when it is rendered.  Defaults to the empty string ''.
      */
     suffix: '',
-    
+
-    /** 
+    /**
      * APIProperty: numDigits
-     * {Integer}
+     * {Integer} The number of digits each coordinate shall have when being
+     *     rendered, Defaults to 5.
      */
     numDigits: 5,
-    
+
-    /** 
+    /**
      * APIProperty: granularity
-     * {Integer} 
+     * {Integer}
      */
     granularity: 10,
 
     /**
-     * APIProperty: emptyString 
+     * APIProperty: emptyString
      * {String} Set this to some value to set when the mouse is outside the
      *     map.
      */
     emptyString: null,
-    
+
-    /** 
+    /**
      * Property: lastXy
      * {<OpenLayers.Pixel>}
      */
@@ -76,14 +93,14 @@ OpenLayers.Control.MousePosition = OpenLayers.Class(OpenLayers.Control, {
 
     /**
      * APIProperty: displayProjection
-     * {<OpenLayers.Projection>} The projection in which the 
+     * {<OpenLayers.Projection>} The projection in which the mouse position is
-     * mouse position is displayed
+     *     displayed.
      */
-    displayProjection: null, 
+    displayProjection: null,
-    
+
     /**
      * Constructor: OpenLayers.Control.MousePosition
-     * 
+     *
      * Parameters:
      * options - {Object} Options for control.
      */
@@ -109,7 +126,7 @@ OpenLayers.Control.MousePosition = OpenLayers.Class(OpenLayers.Control, {
             return false;
         }
     },
-    
+
     /**
      * APIMethod: deactivate
      */
@@ -127,7 +144,7 @@ OpenLayers.Control.MousePosition = OpenLayers.Class(OpenLayers.Control, {
     /**
      * Method: draw
      * {DOMElement}
-     */    
+     */
     draw: function() {
         OpenLayers.Control.prototype.draw.apply(this, arguments);
 
@@ -136,12 +153,12 @@ OpenLayers.Control.MousePosition = OpenLayers.Class(OpenLayers.Control, {
             this.div.top = "";
             this.element = this.div;
         }
-        
+
         return this.div;
     },
-   
+
     /**
-     * Method: redraw  
+     * Method: redraw
      */
     redraw: function(evt) {
 
@@ -160,18 +177,18 @@ OpenLayers.Control.MousePosition = OpenLayers.Class(OpenLayers.Control, {
             }
 
             lonLat = this.map.getLonLatFromPixel(evt.xy);
-            if (!lonLat) { 
+            if (!lonLat) {
                 // map has not yet been properly initialized
                 return;
-            }    
+            }
             if (this.displayProjection) {
-                lonLat.transform(this.map.getProjectionObject(), 
+                lonLat.transform(this.map.getProjectionObject(),
                                  this.displayProjection );
-            }      
+            }
             this.lastXy = evt.xy;
-            
+
         }
-        
+
         var newHtml = this.formatOutput(lonLat);
 
         if (newHtml != this.element.innerHTML) {
@@ -200,7 +217,7 @@ OpenLayers.Control.MousePosition = OpenLayers.Class(OpenLayers.Control, {
         var newHtml =
             this.prefix +
             lonLat.lon.toFixed(digits) +
-            this.separator + 
+            this.separator +
             lonLat.lat.toFixed(digits) +
             this.suffix;
         return newHtml;