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

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();
 
@@ -17,73 +34,74 @@ OpenLayers.Popup.BORDER = "0px";
 OpenLayers.Popup.prototype = {
 
     /** 
-     * Property: events 
-     * {<OpenLayers.Events>} 
+     * Property: 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} 
-    * lonlat - {<OpenLayers.LonLat>} 
-    * size - {<OpenLayers.Size>} 
-    * contentHTML - {String} 
-    * closeBox - {Boolean} 
+    * id - {String} a unqiue identifier for this popup.  If null is passed
+    *               an identifier will be automatically generated. 
+    * lonlat - {<OpenLayers.LonLat>}  The position on the map the popup will
+    *                                 be shown.
+    * 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
@@ -216,11 +239,11 @@ OpenLayers.Popup.prototype = {
     },
 
     /**
-    * Method: moveTo
-    * 
-    * Parameters:
-    * px - {<OpenLayers.Pixel>} 
-    */
+     * Method: moveTo
+     * 
+     * Parameters:
+     * px - {<OpenLayers.Pixel>} the top and left position of the popup div. 
+     */
     moveTo: function(px) {
         if ((px != null) && (this.div != null)) {
             this.div.style.left = px.x + "px";
@@ -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,17 +279,19 @@ OpenLayers.Popup.prototype = {
 
     /**
      * Method: hide
+     * Makes the popup invisible.
      */
     hide: function() {
         OpenLayers.Element.hide(this.div);
     },
 
     /**
-    * Method: setSize
-    * 
-    * Parameters:
-    * size - {<OpenLayers.Size>} 
-    */
+     * Method: setSize
+     * Used to adjust the size of the popup. 
+     *
+     * Parameters:
+     * size - {<OpenLayers.Size>} the new size of the popup in pixels.
+     */
     setSize:function(size) { 
         if (size != undefined) {
             this.size = size; 
@@ -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) {
@@ -297,11 +324,12 @@ OpenLayers.Popup.prototype = {
     },  
     
     /**
-    * Method: setOpacity
-    * 
-    * Parameters:
-    * opacity - {float} 
-    */
+     * Method: setOpacity
+     * Sets the opacity of the popup.
+     * 
+     * Parameters:
+     * opacity - {float} A value between 0.0 (transparent) and 1.0 (solid).   
+     */
     setOpacity:function(opacity) { 
         if (opacity != undefined) {
             this.opacity = opacity; 
@@ -317,11 +345,12 @@ OpenLayers.Popup.prototype = {
     },  
     
     /**
-    * Method: setBorder
-    *
-    * Parameters:
-    * border - {int} 
-    */
+     * Method: setBorder
+     * Sets the border style of the popup.
+     *
+     * Parameters:
+     * border - {String} The border style value. eg 2px 
+     */
     setBorder:function(border) { 
         if (border != undefined) {
             this.border = border;
@@ -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) {