A brilliant patch adding better documentation to all of our controls from an

unnamed contributor on OpenLayers trac. (Closes #1751) git-svn-id: http://svn.openlayers.org/trunk/openlayers@8942 dc9f47b5-9b13-0410-9fdd-eb0c1a62fdaf
2009-03-03 06:30:15 +00:00
parent 92fe77f25c
commit 95c178adf2
27 changed files with 86 additions and 23 deletions
--- a/lib/OpenLayers/Control/ArgParser.js
+++ b/lib/OpenLayers/Control/ArgParser.js
@@ -9,6 +9,11 @@

 /**
 * Class: OpenLayers.Control.ArgParser
+ * The ArgParser control adds location bar querystring parsing functionality 
+ * to an OpenLayers Map.
+ * When added to a Map control, on a page load/refresh, the Map will 
+ * automatically take the href string and parse it for lon, lat, zoom, and 
+ * layers information. 
 *
 * Inherits from:
 *  - <OpenLayers.Control>
@@ -37,6 +42,7 @@ OpenLayers.Control.ArgParser = OpenLayers.Class(OpenLayers.Control, {
     * APIProperty: displayProjection
     * {<OpenLayers.Projection>} Requires proj4js support. 
     *     Projection used when reading the coordinates from the URL. This will
+     *
     *     reproject the map coordinates from the URL into the map's
     *     projection.
     *
--- a/lib/OpenLayers/Control/Attribution.js
+++ b/lib/OpenLayers/Control/Attribution.js
@@ -8,8 +8,8 @@

 /**
 * Class: OpenLayers.Control.Attribution
- * Add attribution from layers to the map display. Uses 'attribution' property
- * of each layer.
+ * The attribution control adds attribution from layers to the map display. 
+ * It uses 'attribution' property of each layer.
 *
 * Inherits from:
 *  - <OpenLayers.Control>
--- a/lib/OpenLayers/Control/Button.js
+++ b/lib/OpenLayers/Control/Button.js
@@ -8,7 +8,8 @@

 /**
 * Class: OpenLayers.Control.Button 
- * A very simple button controlfor use with <OpenLayers.Control.Panel>.
+ * The Button control is a very simple push-button, for use with 
+ * <OpenLayers.Control.Panel>.
 * When clicked, the function trigger() is executed.
 * 
 * Inherits from:
--- a/lib/OpenLayers/Control/DragFeature.js
+++ b/lib/OpenLayers/Control/DragFeature.js
@@ -11,8 +11,8 @@

 /**
 * Class: OpenLayers.Control.DragFeature
- * Move a feature with a drag.  Create a new control with the
- *     <OpenLayers.Control.DragFeature> constructor.
+ * The DragFeature control moves a feature with a drag of the mouse. Create a
+ * new control with the <OpenLayers.Control.DragFeature> constructor.
 *
 * Inherits From:
 *  - <OpenLayers.Control>
--- a/lib/OpenLayers/Control/DragPan.js
+++ b/lib/OpenLayers/Control/DragPan.js
@@ -9,7 +9,7 @@

 /**
 * Class: OpenLayers.Control.DragPan
- * DragPan control.
+ * The DragPan control pans the map with a drag of the mouse.
 *
 * Inherits from:
 *  - <OpenLayers.Control>
--- a/lib/OpenLayers/Control/DrawFeature.js
+++ b/lib/OpenLayers/Control/DrawFeature.js
@@ -10,7 +10,8 @@

 /**
 * Class: OpenLayers.Control.DrawFeature
- * Draws features on a vector layer when active.
+ * The DrawFeature control draws point, line or polygon features on a vector
+ * layer when active.
 *
 * Inherits from:
 *  - <OpenLayers.Control>
--- a/lib/OpenLayers/Control/EditingToolbar.js
+++ b/lib/OpenLayers/Control/EditingToolbar.js
@@ -13,6 +13,9 @@

 /**
 * Class: OpenLayers.Control.EditingToolbar 
+ * The EditingToolbar is a panel of 4 controls to draw polygons, lines, 
+ * points, or to navigate the map by panning. By default it appears in the 
+ * upper right corner of the map.
 * 
 * Inherits from:
 *  - <OpenLayers.Control.Panel>
--- a/lib/OpenLayers/Control/KeyboardDefaults.js
+++ b/lib/OpenLayers/Control/KeyboardDefaults.js
@@ -10,6 +10,11 @@

 /**
 * Class: OpenLayers.Control.KeyboardDefaults
+ * The KeyboardDefaults control adds panning and zooming functions, controlled
+ * with the keyboard. By default arrow keys pan, +/- keys zoom & Page Up/Page
+ * Down/Home/End scroll by three quarters of a page.
+ * 
+ * This control has no visible appearance.
 *
 * Inherits from:
 *  - <OpenLayers.Control>
--- a/lib/OpenLayers/Control/LayerSwitcher.js
+++ b/lib/OpenLayers/Control/LayerSwitcher.js
@@ -8,6 +8,13 @@

 /**
 * Class: OpenLayers.Control.LayerSwitcher
+ * The LayerSwitcher control displays a table of contents for the map. This 
+ * allows the user interface to switch between BaseLasyers and to show or hide
+ * Overlays. By default the switcher is shown minimized on the right edge of 
+ * the map, the user may expand it by clicking on the handle.
+ *
+ * To create the LayerSwitcher outside of the map, pass the Id of a html div 
+ * as the first argument to the constructor.
 * 
 * Inherits from:
 *  - <OpenLayers.Control>
--- a/lib/OpenLayers/Control/MouseDefaults.js
+++ b/lib/OpenLayers/Control/MouseDefaults.js
@@ -8,6 +8,9 @@

 /**
 * Class: OpenLayers.Control.MouseDefaults
+ * This class is DEPRECATED in 2.4 and will be removed by 3.0.
+ * If you need this functionality, use <OpenLayers.Control.Navigation> 
+ * instead!!!
 *
 * This class is DEPRECATED in 2.4 and will be removed by 3.0.
 *     If you need this functionality, use Control.Navigation instead!!!
--- a/lib/OpenLayers/Control/MousePosition.js
+++ b/lib/OpenLayers/Control/MousePosition.js
@@ -9,6 +9,8 @@

 /**
 * Class: OpenLayers.Control.MousePosition
+ * The MousePosition control displays geographic coordinates of the mouse
+ * pointer, as it is moved about the map.
 *
 * Inherits from:
 *  - <OpenLayers.Control>
--- a/lib/OpenLayers/Control/MouseToolbar.js
+++ b/lib/OpenLayers/Control/MouseToolbar.js
@@ -11,7 +11,8 @@
 /**
 * Class: OpenLayers.Control.MouseToolbar
 * This class is DEPRECATED in 2.4 and will be removed by 3.0.
- * If you need this functionality, use Control.NavToolbar instead!!! 
+ * If you need this functionality, use <OpenLayers.Control.NavToolbar>
+ * instead!!! 
 */
 OpenLayers.Control.MouseToolbar = OpenLayers.Class(
                                            OpenLayers.Control.MouseDefaults, {
--- a/lib/OpenLayers/Control/OverviewMap.js
+++ b/lib/OpenLayers/Control/OverviewMap.js
@@ -10,8 +10,10 @@

 /**
 * Class: OpenLayers.Control.OverviewMap
- * Create an overview map to display the extent of your main map and provide
- * additional navigation control.  Create a new overview map with the
+ * The OverMap control creates a small overview map, useful to display the 
+ * extent of a zoomed map and your main map and provide additional 
+ * navigation options to the User.  By default the overview map is drawn in
+ * the lower right corner of the main map. Create a new overview map with the
 * <OpenLayers.Control.OverviewMap> constructor.
 *
 * Inerits from:
--- a/lib/OpenLayers/Control/Pan.js
+++ b/lib/OpenLayers/Control/Pan.js
@@ -8,6 +8,8 @@

 /**
 * Class: OpenLayers.Control.Pan
+ * The Pan control is a single button to pan the map in one direction. For
+ * a more complete control see <OpenLayers.Control.PanPanel>.
 *
 * Inherits from:
 *  - <OpenLayers.Control>
--- a/lib/OpenLayers/Control/PanPanel.js
+++ b/lib/OpenLayers/Control/PanPanel.js
@@ -5,6 +5,9 @@

 /**
 * Class: OpenLayers.Control.PanPanel
+ * The PanPanel is visible control for panning the map North, South, East or
+ * West in small steps. By default it is drawn in the top left corner of the
+ * map.
 *
 * Note: If you wish to use this class with the default images and you want 
 *       it to look nice in ie6, you should add the following, conditionally
--- a/lib/OpenLayers/Control/PanZoom.js
+++ b/lib/OpenLayers/Control/PanZoom.js
@@ -9,6 +9,9 @@

 /**
 * Class: OpenLayers.Control.PanZoom
+ * The PanZoom is a visible control, composed of a
+ * <OpenLayers.Control.PanPanel> and a <OpenLayers.Control.ZoomPanel>. By
+ * default it is drawn in the upper left corner of the map.
 *
 * Inherits from:
 *  - <OpenLayers.Control>
--- a/lib/OpenLayers/Control/PanZoomBar.js
+++ b/lib/OpenLayers/Control/PanZoomBar.js
@@ -9,6 +9,10 @@

 /**
 * Class: OpenLayers.Control.PanZoomBar
+ * The PanZoomBar is a visible control composed of a
+ * <OpenLayers.Control.PanPanel> and a <OpenLayers.Control.ZoomBar>. 
+ * By default it is displayed in the upper left corner of the map as 4
+ * directional arrows above a vertical slider.
 *
 * Inherits from:
 *  - <OpenLayers.Control.PanZoom>
--- a/lib/OpenLayers/Control/Panel.js
+++ b/lib/OpenLayers/Control/Panel.js
@@ -8,6 +8,8 @@

 /**
 * Class: OpenLayers.Control.Panel
+ * The Panel control is a container for other controls. With it toolbars
+ * may be composed.
 *
 * Inherits from:
 *  - <OpenLayers.Control>
--- a/lib/OpenLayers/Control/Permalink.js
+++ b/lib/OpenLayers/Control/Permalink.js
@@ -10,7 +10,11 @@

 /**
 * Class: OpenLayers.Control.Permalink
- * 
+ * The Permalink control is hyperlink that will return the user to the 
+ * current map view. By default it is drawn in the lower right corner of the
+ * map. The href is updated as the map is zoomed, panned and whilst layers
+ * are switched.
+ * `
 * Inherits from:
 *  - <OpenLayers.Control>
 */
--- a/lib/OpenLayers/Control/Scale.js
+++ b/lib/OpenLayers/Control/Scale.js
@@ -9,7 +9,8 @@

 /**
 * Class: OpenLayers.Control.Scale
- * Display a small scale indicator on the map.
+ * The Scale control displays the current map scale as a ratio (e.g. Scale = 
+ * 1:1M). By default it is displayed in the lower right corner of the map.
 *
 * Inherits from:
 *  - <OpenLayers.Control>
--- a/lib/OpenLayers/Control/ScaleLine.js
+++ b/lib/OpenLayers/Control/ScaleLine.js
@@ -8,7 +8,9 @@

 /**
 * Class: OpenLayers.Control.ScaleLine
- * Display a small line indicator representing the current map scale on the map.
+ * The ScaleLine displays a small line indicator representing the current 
+ * map scale on the map. By default it is drawn in the lower left corner of
+ * the map.
 * 
 * Inherits from:
 *  - <OpenLayers.Control>
--- a/lib/OpenLayers/Control/SelectFeature.js
+++ b/lib/OpenLayers/Control/SelectFeature.js
@@ -11,7 +11,8 @@

 /**
 * Class: OpenLayers.Control.SelectFeature
- * Selects vector features from a given layer on click or hover. 
+ * The SelectFeature control selects vector features from a given layer on 
+ * click or hover. 
 *
 * Inherits from:
 *  - <OpenLayers.Control>
--- a/lib/OpenLayers/Control/ZoomBox.js
+++ b/lib/OpenLayers/Control/ZoomBox.js
@@ -9,6 +9,9 @@

 /**
 * Class: OpenLayers.Control.ZoomBox
+ * The ZoomBox control enables zooming directly to a given extent, by drawing 
+ * a box on the map. The box is drawn by holding down shift, whilst dragging 
+ * the mouse.
 *
 * Inherits from:
 *  - <OpenLayers.Control>
--- a/lib/OpenLayers/Control/ZoomIn.js
+++ b/lib/OpenLayers/Control/ZoomIn.js
@@ -8,6 +8,7 @@

 /**
 * Class: OpenLayers.Control.ZoomIn
+ * The ZoomIn control is a button to increase the zoom level of a map.
 *
 * Inherits from:
 *  - <OpenLayers.Control>
--- a/lib/OpenLayers/Control/ZoomOut.js
+++ b/lib/OpenLayers/Control/ZoomOut.js
@@ -8,6 +8,7 @@

 /**
 * Class: OpenLayers.Control.ZoomOut
+ * The ZoomOut control is a button to decrease the zoom level of a map.
 *
 * Inherits from:
 *  - <OpenLayers.Control>
--- a/lib/OpenLayers/Control/ZoomPanel.js
+++ b/lib/OpenLayers/Control/ZoomPanel.js
@@ -11,6 +11,10 @@

 /**
 * Class: OpenLayers.Control.ZoomPanel
+ * The ZoomPanel control is a compact collecton of 3 zoom controls - a 
+ * <OpenLayers.Control.ZoomIn>, a <OpenLayers.Control.ZoomToMaxExtent>, and a
+ * <OpenLayers.Control.ZoomOut>. By default it is drawn in the upper left 
+ * corner of the map.
 *
 * Note: If you wish to use this class with the default images and you want 
 *       it to look nice in ie6, you should add the following, conditionally
--- a/lib/OpenLayers/Control/ZoomToMaxExtent.js
+++ b/lib/OpenLayers/Control/ZoomToMaxExtent.js
@@ -8,7 +8,8 @@

 /**
 * Class: OpenLayers.Control.ZoomToMaxExtent 
- * Implements a very simple button control. Designed to be used with a 
+ * The ZoomToMaxExtent control is a button that zooms out to the maximum
+ * extent of the map. It is designed to be used with a 
 * <OpenLayers.Control.Panel>.
 * 
 * Inherits from: