Merge all changes from the naturaldocs sandbox. This brings all the work that

has been done in the NaturalDocs branch back to trunk. Thanks to everyone who
helped out in making this happen. (I could list people, but the list would
be long, and I'm already mentally on vacation.)


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

lib/OpenLayers/Handler/Point.js

@@ -4,65 +4,73 @@
 
 
 /**
- * Handler to draw a point on the map.  Point is displayed on mouse down,
- * moves on mouse move, and is finished on mouse up.
- * 
- * @class
  * @requires OpenLayers/Handler.js
  * @requires OpenLayers/Geometry/Point.js
+ * 
+ * Class: OpenLayers.Handler.Point
+ * Handler to draw a point on the map.  Point is displayed on mouse down,
+ * moves on mouse move, and is finished on mouse up.  The handler triggers
+ * callbacks for 'done' and 'cancel'.  Create a new instance with the
+ * <OpenLayers.Handler.Point> constructor.
+ * 
+ * Inherits from:
+ *  - <OpenLayers.Handler>
  */
 OpenLayers.Handler.Point = OpenLayers.Class.create();
 OpenLayers.Handler.Point.prototype = 
   OpenLayers.Class.inherit(OpenLayers.Handler, {
     
     /**
-     * @type OpenLayers.Feature.Vector
-     * @private
+     * Property: point
+     * {<OpenLayers.Feature.Vector>} The currently drawn point
      */
     point: null,
 
     /**
-     * @type OpenLayers.Layer.Vector
-     * @private
+     * Property: layer
+     * {<OpenLayers.Layer.Vector>} The temporary drawing layer
      */
     layer: null,
     
     /**
-     * @type Boolean
-     * @private
+     * Property: drawing 
+     * {Boolean} A point is being drawn
      */
     drawing: false,
     
     /**
-     * @type Boolean
-     * @private
+     * Property: mouseDown
+     * {Boolean} The mouse is down
      */
     mouseDown: false,
 
     /**
-     * @type OpenLayers.Pixel
-     * @private
+     * Property: lastDown
+     * {<OpenLayers.Pixel>} Location of the last mouse down
      */
     lastDown: null,
 
     /**
-     * @type OpenLayers.Pixel
-     * @private
+     * Property: lastUp
+     * {<OpenLayers.Pixel>}
      */
     lastUp: null,
 
     /**
-     * @constructor
+     * Constructor: OpenLayers.Handler.Point
+     * Create a new point handler.
      *
-     * @param {OpenLayers.Control} control
-     * @param {Array} callbacks An object with a 'done' property whos value is
-     *                          a function to be called when the point drawing
-     *                          is finished.  The callback should expect to
-     *                          recieve a single argument, the point geometry.
-     *                          If the callbacks object contains a 'cancel' property,
-     *                          this function will be called when the handler is deactivated
-     *                          while drawing.  The cancel should expect to receive a geometry.
-     * @param {Object} options
+     * Parameters:
+     * control - {<OpenLayers.Control>} The control that owns this handler
+     * callbacks - {Array} An object with a 'done' property whos value is a
+     *             function to be called when the point drawing is finished.
+     *             The callback should expect to recieve a single argument,
+     *             the point geometry.  If the callbacks object contains a
+     *             'cancel' property, this function will be called when the
+     *             handler is deactivated while drawing.  The cancel should
+     *             expect to receive a geometry.
+     * options - {Object} An optional object with properties to be set on the
+     *           handler
      */
     initialize: function(control, callbacks, options) {
         // TBD: deal with style
@@ -72,6 +80,7 @@ OpenLayers.Handler.Point.prototype =
     },
     
     /**
+     * APIMethod: activate
      * turn on the handler
      */
     activate: function() {
@@ -87,6 +96,7 @@ OpenLayers.Handler.Point.prototype =
     },
     
     /**
+     * Method: createFeature
      * Add temporary features
      */
     createFeature: function() {
@@ -95,6 +105,7 @@ OpenLayers.Handler.Point.prototype =
     },
 
     /**
+     * APIMethod: deactivate
      * turn off the handler
      */
     deactivate: function() {
@@ -111,6 +122,7 @@ OpenLayers.Handler.Point.prototype =
     },
     
     /**
+     * Method: destroyFeature
      * Destroy the temporary geometries
      */
     destroyFeature: function() {
@@ -118,6 +130,7 @@ OpenLayers.Handler.Point.prototype =
     },
 
     /**
+     * Method: finalize
      * Finish the geometry and call the "done" callback.
      */
     finalize: function() {
@@ -131,6 +144,7 @@ OpenLayers.Handler.Point.prototype =
     },
 
     /**
+     * APIMethod: cancel
      * Finish the geometry and call the "cancel" callback.
      */
     cancel: function() {
@@ -144,7 +158,14 @@ OpenLayers.Handler.Point.prototype =
     },
 
     /**
+     * Method: dblclick
      * Handle double clicks.
+     * 
+     * Parameters:
+     * evt - {Event} The browser event
+     *
+     * Return: 
+     * {Boolean} Allow event propagation
      */
     dblclick: function(evt) {
         OpenLayers.Event.stop(evt);
@@ -152,6 +173,7 @@ OpenLayers.Handler.Point.prototype =
     },
     
     /**
+     * Method: drawFeature
      * Render features on the temporary layer.
      */
     drawFeature: function() {
@@ -159,20 +181,25 @@ OpenLayers.Handler.Point.prototype =
     },
     
     /**
+     * Method: geometryClone
      * Return a clone of the relevant geometry.
      *
-     * @type OpenLayers.Geometry.Point
+     * Return: {<OpenLayers.Geometry.Point>}
      */
     geometryClone: function() {
         return this.point.geometry.clone();
     },
   
     /**
-     * Handle mouse down.  Add a new point to the geometry and render it.
+     * Method: mousedown
+     * Handle mouse down.  Adjust the geometry and redraw.
      * Return determines whether to propagate the event on the map.
      * 
-     * @param {Event} evt
-     * @type Boolean
+     * Parameters:
+     * evt - {Event} The browser event
+     *
+     * Return: 
+     * {Boolean} Allow event propagation
      */
     mousedown: function(evt) {
         // check keyboard modifiers
@@ -196,13 +223,17 @@ OpenLayers.Handler.Point.prototype =
     },
 
     /**
+     * Method: mousemove
      * Handle mouse move.  Adjust the geometry and redraw.
      * Return determines whether to propagate the event on the map.
      * 
-     * @param {Event} evt
-     * @type Boolean
+     * Parameters:
+     * evt - {Event} The browser event
+     *
+     * Return: 
+     * {Boolean} Allow event propagation
      */
-    mousemove: function (evt) {
+	mousemove: function (evt) {
         if(this.drawing) {
             var lonlat = this.map.getLonLatFromPixel(evt.xy);
             this.point.geometry.x = lonlat.lon;
@@ -213,13 +244,17 @@ OpenLayers.Handler.Point.prototype =
     },
 
     /**
+     * Method: mouseup
      * Handle mouse up.  Send the latest point in the geometry to the control.
      * Return determines whether to propagate the event on the map.
-     * 
-     * @param {Event} evt
-     * @type Boolean
+     *
+     * Parameters:
+     * evt - {Event} The browser event
+     *
+     * Return: 
+     * {Boolean} Allow event propagation
      */
-    mouseup: function (evt) {
+	mouseup: function (evt) {
         if(this.drawing) {
             this.finalize();
             return false;
@@ -228,6 +263,9 @@ OpenLayers.Handler.Point.prototype =
         }
     },
 
-    /** @final @type String */
+    /**
+     * Constant: CLASS_NAME
+     * {String} Name of class.
+     */
     CLASS_NAME: "OpenLayers.Handler.Point"
 });