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

@@ -3,41 +3,74 @@
  * for the full text of the license. */
 
 /**
- * Read/WRite GML. 
  * @requires OpenLayers/Format.js
  * @requires OpenLayers/Feature/Vector.js
  * @requires OpenLayers/Ajax.js
  * @requires OpenLayers/Geometry.js
+ *
+ * Class: OpenLayers.Format.GML
+ * Read/Wite GML. 
+ * 
+ * Inherits from:
+ *  - <OpenLayers.Format>
  */
 OpenLayers.Format.GML = OpenLayers.Class.create();
 OpenLayers.Format.GML.prototype = 
   OpenLayers.Class.inherit( OpenLayers.Format, {
     
+    /*
+     * APIProperty: featureNS
+     * Namespace used for feature attributes. Default matches the NS
+     * used by MapServer output.
+     */
     featureNS: "http://mapserver.gis.umn.edu/mapserver",
     
+    /*
+     * APIProperty: featureName
+     * element name for features. Default is 'featureMember'.
+     */
     featureName: "featureMember", 
     
+    /*
+     * APIProperty: layerName
+     * Name of data layer. Default is 'features'.
+     */
+     
     layerName: "features",
     
+    /**
+     * APIProperty: geometry
+     * Name of geometry element.
+     */
     geometryName: "geometry",
     
+    /** 
+     * APIProperty: collectionName
+     * Name of featureCollection element
+     */
     collectionName: "FeatureCollection",
     
+    /**
+     * APIProperty: gmlns
+     * GML Namespace
+     */
     gmlns: "http://www.opengis.net/gml",
     
 
-    /** 
-     * Extract attributes from GML. Most of the time,
-     * this is a significant time usage, due to the need
-     * to recursively descend the XML to search for attributes.
-     * 
-     * @type Boolean */
+    /**
+     * APIProperty: extractAttributes
+     * {Boolean} Extract attributes from GML. Most of the time, this is a
+     * significant time usage, due to the need to recursively descend the XML
+     * to search for attributes.
+     */
     extractAttributes: true,
     
     /**
+     * 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") { 
@@ -73,10 +106,13 @@ OpenLayers.Format.GML.prototype =
      },
 
      /**
+      * Method: parseFeature
       * This function is the core of the GML 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;
@@ -178,10 +214,13 @@ OpenLayers.Format.GML.prototype =
     },        
     
     /**
+     * Method: parseAttributes
      * recursive function parse the attributes of a GML 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;
@@ -208,10 +247,13 @@ OpenLayers.Format.GML.prototype =
     },
     
     /**
+     * Method: parsePolygonNode
+     * 
+     * Parameters:
+     * xmlNode - {XMLNode} 
      *
-     * @param {XMLNode} xmlNode 
-     *
-     * @return {OpenLayers.Geometry.Polygon} polygon geometry
+     * Returns:
+     * {<OpenLayers.Geometry.Polygon>} polygon geometry
      */
     parsePolygonNode: function(polygonNode) {
         var linearRings = OpenLayers.Ajax.getElementsByTagNameNS(polygonNode,
@@ -231,12 +273,14 @@ OpenLayers.Format.GML.prototype =
     },
     
     /**
+     * Method: parseCoords
      * Extract Geographic coordinates from an XML node.
-     * @private
-     * @param {XMLNode} xmlNode 
-     * 
-     * @return an array of OpenLayers.Geometry.Point points.
-     * @type Array
+     *
+     * Parameters:
+     * xmlNode - {<XMLNode>} 
+     *
+     * Returns:
+     * An array of <OpenLayers.Geometry.Point> points.
      */
     parseCoords: function(xmlNode) {
         var x, y, left, bottom, right, top, bounds;
@@ -287,9 +331,12 @@ OpenLayers.Format.GML.prototype =
     },
     
     /**
-     * Accept Feature Collection, and return a string. 
+     * APIMethod: write
+     * Accept Feature Array, and return a string. 
      * 
-     * @param {Array} List of features to serialize into a string.
+     * Parameters:
+     * features - Array({<OpenLayers.Feature.Vector>}> List of features to
+     * serialize into a string.
      */
      write: function(features) {
         var featureCollection = document.createElementNS("http://www.opengis.net/wfs", "wfs:" + this.collectionName);
@@ -300,10 +347,14 @@ OpenLayers.Format.GML.prototype =
      },
     
     /** 
+     * Method: createFeatureXML
      * Accept an OpenLayers.Feature.Vector, and build a geometry for it.
-     * 
-     * @param {OpenLayers.Feature.Vector} feature
-     * @returns {DOMElement}
+     *
+     * Parameters:
+     * feature - {<OpenLayers.Feature.Vector>} 
+     *
+     * Returns:
+     * {DOMElement}
      */
     createFeatureXML: function(feature) {
         var geometryNode = this.buildGeometryNode(feature.geometry);
@@ -326,10 +377,12 @@ OpenLayers.Format.GML.prototype =
         return featureNode;
     },    
     
-    /** 
+    /**
+     * Method: buildGeometryNode 
      * builds a GML file with a given geometry
-     * 
-     * @param {OpenLayers.Geometry} geometry
+     *
+     * Parameters:
+     * geometry - {<OpenLayers.Geometry>} 
      */
     buildGeometryNode: function(geometry) {
     // TBD test if geoserver can be given a Multi-geometry for a simple-geometry data store
@@ -403,11 +456,15 @@ OpenLayers.Format.GML.prototype =
     },
      
     /**
+     * Method: buildCoordinates
      * builds the coordinates XmlNode
      * <gml:coordinates decimal="." cs="," ts=" ">...</gml:coordinates>
      *
-     * @param {OpenLayers.Geometry} geometry
-     * @return {XmlNode} created xmlNode
+     * Parameters: 
+     * geometry - {<OpenLayers.Geometry>} 
+     *
+     * Returns:
+     * {XmlNode} created xmlNode
      */
     buildCoordinatesNode: function(geometry) {
         var coordinatesNode = document.createElementNS(this.gmlns, "gml:coordinates");