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/Format/KML.js

@@ -3,25 +3,33 @@
  * for the full text of the license. */
 
 /**
- * Read only KML. 
  * @requires OpenLayers/Format.js
  * @requires OpenLayers/Feature/Vector.js
  * @requires OpenLayers/Ajax.js
+ * 
+ * Class: OpenLayers.Format.KML
+ * Read only KML. Largely Proof of Concept: does not support advanced Features,
+ * including Polygons.
+ *
+ * Inherits from:
+ *  - <OpenLayers.Format>
  */
 OpenLayers.Format.KML = OpenLayers.Class.create();
 OpenLayers.Format.KML.prototype = 
   OpenLayers.Class.inherit( OpenLayers.Format, {
     
-    featureNS: "http://mapserver.gis.umn.edu/mapserver",
-    
-    collectionName: "FeatureCollection",
-    
+    /**
+     * APIProperty: kmlns
+     * KML Namespace to use. Defaults to 2.0 namespace.
+     */
     kmlns: "http://earth.google.com/kml/2.0",
     
     /**
+     * APIMethod: read
      * Read data from a string, and return a list of features. 
      * 
-     * @param {string|XMLNode} data data to read/parse.
+     * Parameters: 
+     * data - {string} or {XMLNode>} data to read/parse.
      */
      read: function(data) {
         if (typeof data == "string") { 
@@ -43,10 +51,13 @@ OpenLayers.Format.KML.prototype =
      },
 
      /**
+      * Method: parseFeature
       * This function is the core of the KML parsing code in OpenLayers.
       * It creates the geometries that are then attached to the returned
       * feature, and calls parseAttributes() to get attribute data out.
-      * @param {DOMElement} xmlNode
+      *
+      * Parameters:
+      * xmlNode - {<DOMElement>} 
       */
      parseFeature: function(xmlNode) {
         var geom;
@@ -87,10 +98,13 @@ OpenLayers.Format.KML.prototype =
     },        
     
     /**
+     * Method: parseAttributes
      * recursive function parse the attributes of a KML node.
      * Searches for any child nodes which aren't geometries,
      * and gets their value.
-     * @param {DOMElement} xmlNode
+     *
+     * Parameters:
+     * xmlNode - {<DOMElement>} 
      */
     parseAttributes: function(xmlNode) {
         var nodes = xmlNode.childNodes;
@@ -117,12 +131,14 @@ OpenLayers.Format.KML.prototype =
     },
     
     /**
+     * Method: parseCoords
      * Extract Geographic coordinates from an XML node.
-     * @private
-     * @param {XMLNode} xmlNode 
+     *
+     * Parameters:
+     * xmlNode - {<XMLNode>} 
      * 
-     * @return an array of OpenLayers.Geometry.Point points.
-     * @type Array
+     * Returns:
+     * An array of <OpenLayers.Geometry.Point> points.
      */
     parseCoords: function(xmlNode) {
         var p = [];