Documentation improvements provided by Glen Stampoultzis. (Thanks Glen!) Closes

#825, #836.


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

doc/authors.txt

@@ -15,6 +15,7 @@ Tim Schaub
 Christopher Schmidt
 Cameron Shorter                                                              
 Paul Spencer                                                                 
+Glen Stampoultzis
 James Stembridge
 Erik Uzureau
 Bill Woodall

lib/OpenLayers/Control.js

@@ -5,7 +5,49 @@
 /**
  * Class: OpenLayers.Control
  * Controls affect the display or behavior of the map. They allow everything
-* from panning and zooming to displaying a scale indicator.
+ * from panning and zooming to displaying a scale indicator. Controls by 
+ * default are added to the map they are contained within however it is
+ * possible to add a control to an external div by passing the div in the
+ * options parameter.
+ * 
+ * Example:
+ * The following example shows how to add many of the common controls
+ * to a map.
+ * 
+ * > var map = new OpenLayers.Map('map', { controls: [] });
+ * >
+ * > map.addControl(new OpenLayers.Control.PanZoomBar());
+ * > map.addControl(new OpenLayers.Control.MouseToolbar());
+ * > map.addControl(new OpenLayers.Control.LayerSwitcher({'ascending':false}));
+ * > map.addControl(new OpenLayers.Control.Permalink());
+ * > map.addControl(new OpenLayers.Control.Permalink('permalink'));
+ * > map.addControl(new OpenLayers.Control.MousePosition());
+ * > map.addControl(new OpenLayers.Control.OverviewMap());
+ * > map.addControl(new OpenLayers.Control.KeyboardDefaults());
+ *
+ * The next code fragment is a quick example of how to intercept 
+ * shift-mouse click to display the extent of the bounding box
+ * dragged out by the user.  Usually controls are not created
+ * in exactly this manner.  See the source for a more complete 
+ * example:
+ *
+ * > var control = new OpenLayers.Control();
+ * > OpenLayers.Util.extend(control, {
+ * >     draw: function () {
+ * >         // this Handler.Box will intercept the shift-mousedown
+ * >         // before Control.MouseDefault gets to see it
+ * >         this.box = new OpenLayers.Handler.Box( control, 
+ * >             {"done": this.notice},
+ * >             {keyMask: OpenLayers.Handler.MOD_SHIFT});
+ * >         this.box.activate();
+ * >     },
+ * >
+ * >     notice: function (bounds) {
+ * >         alert(bounds);
+ * >     }
+ * > }); 
+ * > map.addControl(control);
+ * 
  */
 OpenLayers.Control = OpenLayers.Class.create();
 
@@ -63,7 +105,12 @@ OpenLayers.Control.prototype = {
 
     /**
      * Constructor: OpenLayers.Control
-     * Create an OpenLayers Control.
+     * Create an OpenLayers Control.  The options passed as a parameter
+     * directly extend the control.  For example passing the following:
+     * 
+     * > var control = new OpenLayers.Control({div: myDiv});
+     *
+     * Overrides the default div attribute value of null.
      * 
      * Parameters:
      * options - {Object} 
@@ -81,6 +128,9 @@ OpenLayers.Control.prototype = {
 
     /**
      * Method: destroy
+     * The destroy method is used to perform any clean up before the control
+     * is dereferenced.  Typically this is where event listeners are removed
+     * to prevent memory leaks.
      */
     destroy: function () {
         // eliminate circular references
@@ -108,9 +158,14 @@ OpenLayers.Control.prototype = {
   
     /**
      * Method: draw
+     * The draw method is called when the control is ready to be displayed
+     * on the page.  If a div has not been created one is created.  Controls
+     * with a visual component will almost always want to override this method 
+     * to customize the look of control. 
      *
      * Parameters:
-     * px - {<OpenLayers.Pixel>} 
+     * px - {<OpenLayers.Pixel>} The top-left pixel position of the control
+     *      or null.
      *
      * Return:
      * {DOMElement} A reference to the DIV DOMElement containing the control
@@ -130,6 +185,8 @@ OpenLayers.Control.prototype = {
 
     /**
      * Method: moveTo
+     * Sets the left and top style attributes to the passed in pixel 
+     * coordinates.
      *
      * Parameters:
      * px - {<OpenLayers.Pixel>}
@@ -143,9 +200,13 @@ OpenLayers.Control.prototype = {
 
     /**
      * Method: activate
+     * Explicitly activates a control and it's associated
+     * handler if one has been set.  Controls can be
+     * deactivated by calling the deactivate() method.
      * 
      * Return:
-     * {Boolean}
+     * {Boolean}  True if the control was successfully activated or
+     *            false if the control was already active.
      */
     activate: function () {
         if (this.active) {
@@ -160,9 +221,12 @@ OpenLayers.Control.prototype = {
     
     /**
      * Method: deactivate
+     * Deactivates a control and it's associated handler if any.  The exact
+     * effect of this depends on the control itself.
      * 
      * Return:
-     * {Boolean}
+     * {Boolean} True if the control was effectively deactivated or false
+     *           if the control was already inactive.
      */
     deactivate: function () {
         if (this.active) {

lib/OpenLayers/Icon.js

@@ -5,6 +5,15 @@
 
 /**
  * Class: OpenLayers.Icon
+ * 
+ * The icon represents a graphical icon on the screen.  Typically used in
+ * conjunction with a <OpenLayers.Marker> to represent markers on a screen.
+ *
+ * An icon has a url, size and position.  It also contains an offset which 
+ * allows the center point to be represented correctly.  This can be
+ * provided either as a fixed offset or a function provided to calculate
+ * the desired offset. 
+ * 
  */
 OpenLayers.Icon = OpenLayers.Class.create();
 OpenLayers.Icon.prototype = {
@@ -65,7 +74,8 @@ OpenLayers.Icon.prototype = {
     
     /** 
      * Method: destroy
-     * nullify references to prevent circular references and memory leaks
+     * Nullify references and remove event listeners to prevent circular 
+     * references and memory leaks
      */
     destroy: function() {
         OpenLayers.Event.stopObservingElement(this.imageDiv.firstChild); 

lib/OpenLayers/Map.js

@@ -10,6 +10,10 @@
  * Class: OpenLayers.Map
  * Instances of OpenLayers.Map are interactive maps embedded in a web page.
  * Create a new map with the <OpenLayers.Map> constructor.
+ * 
+ * On their own maps do not provide much functionality.  To extend a map
+ * it's necessary to add controls (<OpenLayers.Control>) and 
+ * layers (<OpenLayers.Layer>) to the map. 
  */
 OpenLayers.Map = OpenLayers.Class.create();
 /**

lib/OpenLayers/Marker.js

@@ -10,13 +10,28 @@
  * Class: OpenLayers.Marker
  * Instances of OpenLayers.Marker are a combination of a 
  * <OpenLayers.LonLat> and an <OpenLayers.Icon>.  
+ *
+ * Markers are generally added to a special layer called
+ * <OpenLayers.Layer.Makers>.
+ *
+ * Example:
+ * (code)
+ * var markers = new OpenLayers.Layer.Markers( "Markers" );
+ * map.addLayer(markers);
+ *
+ * var size = new OpenLayers.Size(10,17);
+ * var offset = new OpenLayers.Pixel(-(size.w/2), -size.h);
+ * var icon = new OpenLayers.Icon('http://boston.openguides.org/markers/AQUA.png',size,offset);
+ * markers.addMarker(new OpenLayers.Marker(new OpenLayers.LonLat(0,0),icon));
+ *
+ * (end)
  */
 OpenLayers.Marker = OpenLayers.Class.create();
 OpenLayers.Marker.prototype = {
     
     /** 
      * Property: icon 
-     * {<OpenLayers.Icon>} 
+     * {<OpenLayers.Icon>} The icon used by this marker.
      */
     icon: null,
 
@@ -28,21 +43,21 @@ OpenLayers.Marker.prototype = {
     
     /** 
      * Property: events 
-     * {<OpenLayers.Events>}
+     * {<OpenLayers.Events>} the event handler.
      */
     events: null,
     
     /** 
      * Property: map 
-     * {<OpenLayers.Map>}
+     * {<OpenLayers.Map>} the map this marker is attached to
      */
     map: null,
     
     /** 
      * Constructor: OpenLayers.Marker
      * Paraemeters:
-     * icon - {<OpenLayers.Icon>}
+     * icon - {<OpenLayers.Icon>}  the icon for this marker
-     * lonlat - {<OpenLayers.LonLat>}
+     * lonlat - {<OpenLayers.LonLat>} the position of this marker
      */
     initialize: function(lonlat, icon) {
         this.lonlat = lonlat;
@@ -91,7 +106,7 @@ OpenLayers.Marker.prototype = {
     * Move the marker to the new location.
     *
     * Parameters:
-    * px - {<OpenLayers.Pixel>}
+    * px - {<OpenLayers.Pixel>} the pixel position to move to
     */
     moveTo: function (px) {
         if ((px != null) && (this.icon != null)) {
@@ -118,9 +133,11 @@ OpenLayers.Marker.prototype = {
     
     /**
      * Method: inflate
+     * Englarges the markers icon by the specified ratio.
      *
      * Parameters:
-     * inflate - {float}
+     * inflate - {float} the ratio to enlarge the marker by (passing 2
+     *                   will double the size).
      */
     inflate: function(inflate) {
         if (this.icon) {

lib/OpenLayers/Popup.js

@@ -5,6 +5,23 @@
 
 /**
  * Class: OpenLayers.Popup
+ *
+ * A popup is a small div that can opened and closed on the map.
+ * Typically opened in response to clicking on a marker.  
+ * See <OpenLayers.Marker>.  Popup's don't require their own
+ * layer and are added the the map using the <OpenLayers.Map.addPopup>
+ * method.
+ *
+ * Example:
+ * (code)
+ * popup = new OpenLayers.Popup("chicken", 
+ *                    new OpenLayers.LonLat(5,40),
+ *                    new OpenLayers.Size(200,200),
+ *                    "example popup",
+ *                    true);
+ *       
+ * map.addPopup(popup);
+ * (end)
  */
 OpenLayers.Popup = OpenLayers.Class.create();
 
@@ -18,72 +35,73 @@ OpenLayers.Popup.prototype = {
 
     /** 
      * Property: events  
-     * {<OpenLayers.Events>} 
+     * {<OpenLayers.Events>} custom event manager 
      */
     events: null,
     
     /** Property: id
-     * {String}
+     * {String} the unique identifier assigned to this popup.
      */
     id: "",
 
     /** 
      * Property: lonlat 
-     * {<OpenLayers.LonLat>} 
+     * {<OpenLayers.LonLat>} the position of this popup on the map
      */
     lonlat: null,
 
     /** 
      * Property: div 
-     * {DOMElement} 
+     * {DOMElement} the div that contains this popup.
      */
     div: null,
 
     /** 
      * Property: size 
-     * {<OpenLayers.Size>} 
+     * {<OpenLayers.Size>} the width and height of the popup.
      */
     size: null,    
 
     /** 
      * Property: contentHTML 
-     * {String} 
+     * {String} The HTML that this popup displays.
      */
     contentHTML: "",
     
     /** 
      * Property: backgroundColor 
-     * {String} 
+     * {String} the background color used by the popup.
      */
     backgroundColor: "",
     
     /** 
      * Property: opacity 
-     * {float} 
+     * {float} the opacity of this popup (between 0.0 and 1.0)
      */
     opacity: "",
 
     /** 
      * Property: border 
-     * {String} 
+     * {String} the border size of the popup.  (eg 2px)
      */
     border: "",
     
     /** 
      * Property: contentDiv 
-     * {DOMElement} 
+     * {DOMElement} a reference to the element that holds the content of
+     *              the div.
      */
     contentDiv: null,
     
     /** 
      * Property: groupDiv 
-     * {DOMElement} 
+     * {DOMElement} the parent of <OpenLayers.Popup.contentDiv> 
      */
     groupDiv: null,
 
     /** 
      * Property: padding 
-     * {int} 
+     * {int} the internal padding of the content div.
      */
     padding: 5,
 
@@ -99,11 +117,15 @@ OpenLayers.Popup.prototype = {
     * Create a popup.
     * 
     * Parameters: 
-    * id - {String} 
+    * id - {String} a unqiue identifier for this popup.  If null is passed
-    * lonlat - {<OpenLayers.LonLat>} 
+    *               an identifier will be automatically generated. 
-    * size - {<OpenLayers.Size>} 
+    * lonlat - {<OpenLayers.LonLat>}  The position on the map the popup will
-    * contentHTML - {String} 
+    *                                 be shown.
-    * closeBox - {Boolean} 
+    * size - {<OpenLayers.Size>}      The size of the popup.
+    * contentHTML - {String}          The HTML content to display inside the 
+    *                                 popup.
+    * closeBox - {Boolean}            Whether to display a close box inside
+    *                                 the popup. 
     */
     initialize:function(id, lonlat, size, contentHTML, closeBox) {
         if (id == null) {
@@ -178,10 +200,11 @@ OpenLayers.Popup.prototype = {
     },
 
     /** 
-    * method: draw
+    * Method: draw
+    * Constructs the elements that make up the popup.
     *
     * Parameters:
-    * px - {<OpenLayers.Pixel>} 
+    * px - {<OpenLayers.Pixel>} the position the popup in pixels.
     * 
     * Return:
     * {DOMElement} Reference to a div that contains the drawn popup
@@ -219,7 +242,7 @@ OpenLayers.Popup.prototype = {
      * Method: moveTo
      * 
      * Parameters:
-    * px - {<OpenLayers.Pixel>} 
+     * px - {<OpenLayers.Pixel>} the top and left position of the popup div. 
      */
     moveTo: function(px) {
         if ((px != null) && (this.div != null)) {
@@ -229,7 +252,7 @@ OpenLayers.Popup.prototype = {
     },
 
     /**
-     * method: visible
+     * Method: visible
      *
      * Returns:      
      * {Boolean} Boolean indicating whether or not the popup is visible
@@ -240,6 +263,7 @@ OpenLayers.Popup.prototype = {
 
     /**
      * Method: toggle
+     * Toggles visibility of the popup.
      */
     toggle: function() {
         OpenLayers.Element.toggle(this.div);
@@ -247,6 +271,7 @@ OpenLayers.Popup.prototype = {
 
     /**
      * Method: show
+     * Makes the popup visible.
      */
     show: function() {
         OpenLayers.Element.show(this.div);
@@ -254,6 +279,7 @@ OpenLayers.Popup.prototype = {
 
     /**
      * Method: hide
+     * Makes the popup invisible.
      */
     hide: function() {
         OpenLayers.Element.hide(this.div);
@@ -261,9 +287,10 @@ OpenLayers.Popup.prototype = {
 
     /**
      * Method: setSize
+     * Used to adjust the size of the popup. 
      *
      * Parameters:
-    * size - {<OpenLayers.Size>} 
+     * size - {<OpenLayers.Size>} the new size of the popup in pixels.
      */
     setSize:function(size) { 
         if (size != undefined) {
@@ -282,9 +309,9 @@ OpenLayers.Popup.prototype = {
 
     /**
     * Method: setBackgroundColor
-    *
+    * Sets the background color of the popup.
     * Parameters:
-    * color - {String} 
+    * color - {String} the background color.  eg "#FFBBBB"
     */
     setBackgroundColor:function(color) { 
         if (color != undefined) {
@@ -298,9 +325,10 @@ OpenLayers.Popup.prototype = {
     
     /**
      * Method: setOpacity
+     * Sets the opacity of the popup.
      * 
      * Parameters:
-    * opacity - {float} 
+     * opacity - {float} A value between 0.0 (transparent) and 1.0 (solid).   
      */
     setOpacity:function(opacity) { 
         if (opacity != undefined) {
@@ -318,9 +346,10 @@ OpenLayers.Popup.prototype = {
     
     /**
      * Method: setBorder
+     * Sets the border style of the popup.
      *
      * Parameters:
-    * border - {int} 
+     * border - {String} The border style value. eg 2px 
      */
     setBorder:function(border) { 
         if (border != undefined) {
@@ -334,9 +363,10 @@ OpenLayers.Popup.prototype = {
     
     /**
      * Method: setContentHTML
+     * Allows the user to set the HTML content of the popup.
      *
      * Parameters:
-     * contentHTML - {String} 
+     * contentHTML - {String} HTML for the div.
      */
     setContentHTML:function(contentHTML) {
         if (contentHTML != null) {