diff --git a/doc/authors.txt b/doc/authors.txt
index 3b43ca2b06..770daa580c 100644
--- a/doc/authors.txt
+++ b/doc/authors.txt
@@ -15,6 +15,7 @@ Tim Schaub
 Christopher Schmidt
 Cameron Shorter                                                              
 Paul Spencer                                                                 
+Glen Stampoultzis
 James Stembridge
 Erik Uzureau
 Bill Woodall
diff --git a/lib/OpenLayers/Control.js b/lib/OpenLayers/Control.js
index 2b80b760c6..e00d9dfb47 100644
--- a/lib/OpenLayers/Control.js
+++ b/lib/OpenLayers/Control.js
@@ -3,10 +3,52 @@
  * for the full text of the license. */
 
 /**
-* Class: OpenLayers.Control
-* Controls affect the display or behavior of the map. They allow everything
-* from panning and zooming to displaying a scale indicator.
-*/
+ * Class: OpenLayers.Control
+ * Controls affect the display or behavior of the map. They allow everything
+ * 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();
 
 OpenLayers.Control.TYPE_BUTTON = 1;
@@ -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
@@ -93,8 +143,8 @@ OpenLayers.Control.prototype = {
     /** 
      * Method: setMap
      * Set the map property for the control. This is done through an accessor
-     *   so that subclasses can override this and take special action once 
-     *   they have their map variable set. 
+     * so that subclasses can override this and take special action once 
+     * they have their map variable set. 
      *
      * Parameters:
      * map - {<OpenLayers.Map>} 
@@ -107,10 +157,15 @@ OpenLayers.Control.prototype = {
     },
   
     /**
-     * Method: draw 
+     * 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) {
diff --git a/lib/OpenLayers/Icon.js b/lib/OpenLayers/Icon.js
index 74ea757982..c02f5a0334 100644
--- a/lib/OpenLayers/Icon.js
+++ b/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); 
diff --git a/lib/OpenLayers/Map.js b/lib/OpenLayers/Map.js
index 9248f70c2a..a9f46e5e02 100644
--- a/lib/OpenLayers/Map.js
+++ b/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();
 /**
diff --git a/lib/OpenLayers/Marker.js b/lib/OpenLayers/Marker.js
index 21fc223507..b7f376bdfd 100644
--- a/lib/OpenLayers/Marker.js
+++ b/lib/OpenLayers/Marker.js
@@ -9,14 +9,29 @@
  * 
  * Class: OpenLayers.Marker
  * Instances of OpenLayers.Marker are a combination of a 
- * <OpenLayers.LonLat> and an <OpenLayers.Icon>.
+ * <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>}
-     * lonlat - {<OpenLayers.LonLat>}
+     * icon - {<OpenLayers.Icon>}  the icon for this marker
+     * 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) {
diff --git a/lib/OpenLayers/Popup.js b/lib/OpenLayers/Popup.js
index 0570fa9765..2fbd0fee44 100644
--- a/lib/OpenLayers/Popup.js
+++ b/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) {