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/Geometry.js

@@ -3,45 +3,58 @@
  * for the full text of the license. */
  
 /**
- * @class
  * @requires OpenLayers/Format/WKT.js
  * @requires OpenLayers/Feature/Vector.js
+ * 
+ * Class: OpenLayers.Geometry
+ * A Geometry is a description of a geographic object.  Create an instance of
+ * this class with the <OpenLayers.Geometry> constructor.  This is a base class,
+ * typical geometry types are described by subclasses of this class.
  */
 OpenLayers.Geometry = OpenLayers.Class.create();
 OpenLayers.Geometry.prototype = {
 
-    /** @type String */
+    /**
+     * Property: id
+     * {String} A unique identifier for this geometry.
+     */
     id: null,
 
-    /** This is set when a Geometry is added as Component of another Geometry
-     * 
-     * @type OpenLayers.Geometry */
+    /**
+     * Property: parent
+     * {<OpenLayers.Geometry>}This is set when a Geometry is added as component
+     * of another geometry
+     */
     parent: null,
 
-    /** @type OpenLayers.Bounds */
+    /**
+     * Property: bounds 
+     * {<OpenLayers.Bounds>} The bounds of this geometry
+     */
     bounds: null,
 
     /**
-     * @constructor
+     * Constructor: OpenLayers.Geometry
+     * Creates a geometry object.  
      */
     initialize: function() {
         this.id = OpenLayers.Util.createUniqueID(this.CLASS_NAME+ "_");
     },
     
     /**
-     * 
+     * Method: destroy
+     * Destroy this geometry.
      */
     destroy: function() {
         this.id = null;
-
         this.bounds = null;
-
     },
     
     /**
      * Set the bounds for this Geometry.
      * 
-     * @param {OpenLayers.Bounds} object
+     * Parameters:
+     * object - {<OpenLayers.Bounds>} 
      */
     setBounds: function(bounds) {
         if (bounds) {
@@ -50,6 +63,7 @@ OpenLayers.Geometry.prototype = {
     },
     
     /**
+     * Method: clearBounds
      * Nullify this components bounds and that of its parent as well.
      */
     clearBounds: function() {
@@ -60,10 +74,12 @@ OpenLayers.Geometry.prototype = {
     },
     
     /**
+     * Method: extendBounds
      * Extend the existing bounds to include the new bounds. 
      * If geometry's bounds is not yet set, then set a new Bounds.
      * 
-     * @param {OpenLayers.Bounds} newBounds
+     * Parameters:
+     * newBounds - {<OpenLayers.Bounds>} 
      */
     extendBounds: function(newBounds){
         var bounds = this.getBounds();
@@ -75,10 +91,12 @@ OpenLayers.Geometry.prototype = {
     },
     
     /**
+     * APIMethod: getBounds
      * Get the bounds for this Geometry. If bounds is not set, it 
      * is calculated again, this makes queries faster.
      * 
-     * @type OpenLayers.Bounds
+     * Return:
+     * {<OpenLayers.Bounds>}
      */
     getBounds: function() {
         if (this.bounds == null) {
@@ -87,8 +105,9 @@ OpenLayers.Geometry.prototype = {
         return this.bounds;
     },
     
-    /** Recalculate the bounds for the geometry. 
-     * 
+    /** 
+     * APIMethod: calculateBounds
+     * Recalculate the bounds for the geometry. 
      */
     calculateBounds: function() {
         //
@@ -97,15 +116,17 @@ OpenLayers.Geometry.prototype = {
     },
     
     /**
-     * Note: This is only an approximation based on the bounds of the 
+     * Method: atPoint
+     * Note - This is only an approximation based on the bounds of the 
      * geometry.
      * 
-     * @param {OpenLayers.LonLat} lonlat
-     * @param {float} toleranceLon Optional tolerance in Geometric Coords
-     * @param {float} toleranceLat Optional tolerance in Geographic Coords
+     * Parameters:
+     * lonlat - {<OpenLayers.LonLat>} 
+     * toleranceLon - {float} Optional tolerance in Geometric Coords
+     * toleranceLat - {float} Optional tolerance in Geographic Coords
      * 
-     * @returns Whether or not the geometry is at the specified location
-     * @type Boolean
+     * Return:
+     * {Boolean} Whether or not the geometry is at the specified location
      */
     atPoint: function(lonlat, toleranceLon, toleranceLat) {
         var atPoint = false;
@@ -127,8 +148,12 @@ OpenLayers.Geometry.prototype = {
     },
     
     /**
-     * @returns The length of the geometry
-     * @type float
+     * Method: getLength
+     * Calculate the length of this geometry. This method is defined in
+     * subclasses.
+     * 
+     * Return:
+     * {Float} The length of the collection by summing its parts
      */
     getLength: function() {
         //to be overridden by geometries that actually have a length
@@ -137,8 +162,11 @@ OpenLayers.Geometry.prototype = {
     },
 
     /**
-     * @returns The area of the geometry
-     * @type float
+     * Method: getArea
+     * Calculate the area of this geometry. This method is defined in subclasses.
+     * 
+     * Return:
+     * {Float} The area of the collection by summing its parts
      */
     getArea: function() {
         //to be overridden by geometries that actually have an area
@@ -147,8 +175,11 @@ OpenLayers.Geometry.prototype = {
     },
 
     /**
-     * @returns the Well-Known Text representation of a geometry
-     * @type String
+     * Method: toString
+     * Returns the Well-Known Text representation of a geometry
+     *
+     * Return:
+     * {String} Well-Known Text
      */
     toString: function() {
         return OpenLayers.Format.WKT.prototype.write(
@@ -156,6 +187,6 @@ OpenLayers.Geometry.prototype = {
         );
     },
 
-    /** @final @type String */
+    /** @final @type String*/
     CLASS_NAME: "OpenLayers.Geometry"
 };