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

@@ -3,7 +3,9 @@
  * for the full text of the license. */
 
 /**
- * @class
+ * @requires OpenLayers/Geometry/LineString.js
+ * 
+ * Class: OpenLayers.Geometry.LinearRing
  * 
  * A Linear Ring is a special LineString which is closed. It closes itself 
  * automatically on every addPoint/removePoint by adding a copy of the first
@@ -12,29 +14,31 @@
  * Also, as it is the first in the line family to close itself, a getArea()
  * function is defined to calculate the enclosed area of the linearRing
  * 
- * @requires OpenLayers/Geometry/LineString.js
+ * Inherits:
+ *  - <OpenLayers.Geometry.LineString>
  */
 OpenLayers.Geometry.LinearRing = OpenLayers.Class.create();
 OpenLayers.Geometry.LinearRing.prototype = 
     OpenLayers.Class.inherit(OpenLayers.Geometry.LineString, {
 
     /**
-     * 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: ["OpenLayers.Geometry.Point"],
 
     /**
+     * Constructor: OpenLayers.Geometry.LinearRing
      * Linear rings are constructed with an array of points.  This array
-     * can represent a closed or open ring.  If the ring is open (the last
-     * point does not equal the first point), the constructor will close
-     * the ring.  If the ring is already closed (the last point does equal
-     * the first point), it will be left closed.
+     *     can represent a closed or open ring.  If the ring is open (the last
+     *     point does not equal the first point), the constructor will close
+     *     the ring.  If the ring is already closed (the last point does equal
+     *     the first point), it will be left closed.
      * 
-     * @constructor
-     * @param {Array(OpenLayers.Geometry.Point)} points
+     * Parameters:
+     * points - {Array(<OpenLayers.Geometry.Point>)} points
      */
     initialize: function(points) {
         OpenLayers.Geometry.LineString.prototype.initialize.apply(this, 
@@ -42,17 +46,21 @@ OpenLayers.Geometry.LinearRing.prototype =
     },
 
     /**
+     * APIMethod: addComponent
      * Adds a point to geometry components.  If the point is to be added to
-     * the end of the components array and it is the same as the last point
-     * already in that array, the duplicate point is not added.  This has the
-     * effect of closing the ring if it is not already closed, and doing the
-     * right thing if it is already closed.  This behavior can be overridden
-     * by calling the method with a non-null index as the second argument.
+     *     the end of the components array and it is the same as the last point
+     *     already in that array, the duplicate point is not added.  This has 
+     *     the effect of closing the ring if it is not already closed, and 
+     *     doing the right thing if it is already closed.  This behavior can 
+     *     be overridden by calling the method with a non-null index as the 
+     *     second argument.
      *
-     * @param {OpenLayers.Geometry.Point} point
-     * @param {int} index Index into the array to insert the component
-     * @type Boolean
-     * @return Point was successfully added
+     * Parameter:
+     * point - {<OpenLayers.Geometry.Point>}
+     * index - {Integer} Index into the array to insert the component
+     * 
+     * Return:
+     * {Boolean} Was the Point successfully added?
      */
     addComponent: function(point, index) {
         var added = false;
@@ -78,9 +86,11 @@ OpenLayers.Geometry.LinearRing.prototype =
     },
     
     /**
-     * Removes a point from geometry components
+     * APIMethod: removeComponent
+     * Removes a point from geometry components.
      *
-     * @param {OpenLayers.Geometry.Point} point
+     * Parameters:
+     * point - {<OpenLayers.Geometry.Point>}
      */
     removeComponent: function(point) {
         if (this.components.length > 4) {
@@ -100,11 +110,13 @@ OpenLayers.Geometry.LinearRing.prototype =
         }
     },
     
-    /** Note: The area is positive if the ring is oriented CW, otherwise
+    /**
+     * APIMethod: getArea
+     * Note - The area is positive if the ring is oriented CW, otherwise
      *         it will be negative.
      * 
-     * @returns The signed area for a ring.
-     * @type float
+     * Return:
+     * {Float} The signed area for a ring.
      */
     getArea: function() {
         var area = 0.0;