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

@@ -3,40 +3,50 @@
  * for the full text of the license. */
 
 /**
- * @class
+ * @requires OpenLayers/Geometry.js
  *
+ * Class: OpenLayers.Geometry.Collection
  * A Collection is exactly what it sounds like: A collection of different 
- * Geometries. These are stored in the local parameter "components" (which
+ * Geometries. These are stored in the local parameter <components> (which
  * can be passed as a parameter to the constructor). 
  * 
  * As new geometries are added to the collection, they are NOT cloned. 
  * When removing geometries, they need to be specified by reference (ie you 
  * have to pass in the *exact* geometry to be removed).
  * 
- * The getArea() and getLength() functions here merely iterate through
+ * The <getArea> and <getLength> functions here merely iterate through
  * the components, summing their respective areas and lengths.
- * 
- * @requires OpenLayers/Geometry.js
+ *
+ * Create a new instance with the <OpenLayers.Geometry.Collection> constructor.
+ *
+ * Inerhits from:
+ *  - <OpenLayers.Geometry> 
  */
 OpenLayers.Geometry.Collection = OpenLayers.Class.create();
 OpenLayers.Geometry.Collection.prototype = 
   OpenLayers.Class.inherit( OpenLayers.Geometry, {
 
-    /** @type Array(OpenLayers.Geometry) */
+    /**
+     * APIProperty: components
+     * {Array(<OpenLayers.Geometry>)} The component parts of this geometry
+     */
     components: null,
     
     /**
-     * An array of class names representing the types of components that
-     * the collection can include.  A null value means the component types
-     * are not restricted.
-     * @type Array(String)
+     * Property: componentTypes
+     * {Array(String)} An array of class names representing the types of
+     * components that the collection can include.  A null value means the
+     * component types are not restricted.
      */
     componentTypes: null,
 
     /**
-     * @constructor
-     * 
-     * @param {Array(OpenLayers.Geometry)} components
+     * Constructor: OpenLayers.Geometry.Collection
+     * Creates a Geometry Collection -- a list of geoms.
+     *
+     * Parameters: 
+     * components - {Array(<OpenLayers.Geometry>)} Optional array of geometries
+     *
      */
     initialize: function (components) {
         OpenLayers.Geometry.prototype.initialize.apply(this, arguments);
@@ -47,7 +57,8 @@ OpenLayers.Geometry.Collection.prototype =
     },
 
     /**
-     * 
+     * APIMethod: destroy
+     * Destroy this geometry.
      */
     destroy: function () {
         this.components.length = 0;
@@ -55,8 +66,11 @@ OpenLayers.Geometry.Collection.prototype =
     },
 
     /**
-     * @returns An exact clone of this collection
-     * @type OpenLayers.Geometry.Collection
+     * APIMethod: clone
+     * Clone this geometry.
+     *
+     * Return:
+     * {<OpenLayers.Geometry.Collection>} An exact clone of this collection
      */
     clone: function() {
         var geometry = eval("new " + this.CLASS_NAME + "()");
@@ -71,8 +85,11 @@ OpenLayers.Geometry.Collection.prototype =
     },
 
     /**
-     * @returns the components of the geometry
-     * @type String
+     * Method: getComponentsString
+     * Get a string representing the components for this collection
+     * 
+     * Return:
+     * {String} A string representation of the components of this geometry
      */
     getComponentsString: function(){
         var strings = [];
@@ -82,9 +99,10 @@ OpenLayers.Geometry.Collection.prototype =
         return strings.join(",");
     },
 
-    /** Recalculate the bounds by iterating through the components and 
-     *   calling calling extendBounds() on each item
-     * 
+    /**
+     * APIMethod: calculateBounds
+     * Recalculate the bounds by iterating through the components and 
+     * calling calling extendBounds() on each item.
      */
     calculateBounds: function() {
         this.bounds = null;
@@ -97,8 +115,11 @@ OpenLayers.Geometry.Collection.prototype =
     },
 
     /**
-     * @param {Array(OpenLayers.Geometry)} components
-     * 
+     * APIMethod: addComponents
+     * Add components to this geometry.
+     *
+     * Parameters:
+     * components - {Array(<OpenLayers.Geometry>)} An array of geometries to add
      */
     addComponents: function(components){
         if(!(components instanceof Array)) {
@@ -110,16 +131,19 @@ OpenLayers.Geometry.Collection.prototype =
     },
 
     /**
+     * Method: addComponent
      * Add a new component (geometry) to the collection.  If this.componentTypes
      * is set, then the component class name must be in the componentTypes array.
-     * 
+     *
      * The bounds cache is reset.
      * 
-     * @param {OpenLayers.Geometry} component
-     * @param {int} index Index into the array to insert the component
-     * @type Boolean
-     * @return Component was successfully added
-    */    
+     * Parameters:
+     * component - {<OpenLayers.Geometry>} A geometry to add
+     * index - {int} Optional index into the array to insert the component
+     *
+     * Return:
+     * {Boolean} The component geometry was successfully added
+     */    
     addComponent: function(component, index) {
         var added = false;
         if(component) {
@@ -145,7 +169,11 @@ OpenLayers.Geometry.Collection.prototype =
     },
     
     /**
-     * @param {Array(OpenLayers.Geometry)} components
+     * APIMethod: removeComponents
+     * Remove components from this geometry.
+     *
+     * Parameters:
+     * components - {Array(<OpenLayers.Geometry>)} The components to be removed
      */
     removeComponents: function(components) {
         if(!(components instanceof Array)) {
@@ -157,7 +185,11 @@ OpenLayers.Geometry.Collection.prototype =
     },
     
     /**
-     * @param {OpenLayers.Geometry} component
+     * Method: removeComponent
+     * Remove a component from this geometry.
+     *
+     * Parameters:
+     * component - {<OpenLayers.Geometry>} 
      */
     removeComponent: function(component) {
         
@@ -169,8 +201,11 @@ OpenLayers.Geometry.Collection.prototype =
     },
 
     /**
-     * @returns The length of the geometry
-     * @type float 
+     * APIMethod: getLength
+     * Calculate the length of this geometry
+     *
+     * Return:
+     * {Float} The length of the geometry
      */
     getLength: function() {
         var length = 0.0;
@@ -180,10 +215,13 @@ OpenLayers.Geometry.Collection.prototype =
         return length;
     },
     
-    /** Note how this function is overridden in Polygon
-     * 
-     * @returns the area of the collection by summing its parts
-     * @type float
+    /**
+     * APIMethod: getArea
+     * Calculate the area of this geometry. Note how this function is overridden
+     * in <OpenLayers.Geometry.Polygon>.
+     *
+     * Return:
+     * {Float} The area of the collection by summing its parts
      */
     getArea: function() {
         var area = 0.0;
@@ -194,9 +232,12 @@ OpenLayers.Geometry.Collection.prototype =
     },
 
     /**
+     * APIMethod: move
      * Moves a collection in place
-     * @param {Float} x
-     * @param {Float} y
+     *
+     * Parameters:
+     * x - {Float} The x-displacement (in map units)
+     * y - {Float} The y-displacement (in map units)
      */
     move: function(x, y) {
         for(var i = 0; i < this.components.length; i++) {
@@ -205,10 +246,14 @@ OpenLayers.Geometry.Collection.prototype =
     },
 
     /**
+     * APIMethod: equals
      * Tests for equivalent geometries
-     * @param {OpenLayers.Geometry}
-     * @type Boolean
-     * @return The coordinates are equivalent
+     *
+     * Parameters:
+     * geometry - {<OpenLayers.Geometry>}
+     *
+     * Return:
+     * {Boolean} The coordinates are equivalent
      */
     equals: function(geometry) {
         var equivalent = true;
@@ -228,6 +273,9 @@ OpenLayers.Geometry.Collection.prototype =
         return equivalent;
     },
 
-    /** @final @type String */
+    /**
+     * Constant: CLASS_NAME
+     * {String} Name of class.
+     */
     CLASS_NAME: "OpenLayers.Geometry.Collection"
 });