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

@@ -3,35 +3,63 @@
  * for the full text of the license. */
 
 /**
- * Base class for format reading/writing. 
  * @requires OpenLayers/Util.js
+ * 
+ * Class: OpenLayers.Format
+ * Base class for format reading/writing a variety of formats.  Subclasses
+ * of OpenLayers.Format are expected to have read and write methods.
  */
 OpenLayers.Format = OpenLayers.Class.create();
 OpenLayers.Format.prototype = {
     
+    /**
+     * Constructor: OpenLayers.Format
+     * Instances of this class are not useful.  See one of the subclasses.
+     *
+     * Parameters:
+     * options - {Object} An optional object with properties to set on the
+     *           format
+     *
+     * Return:
+     * An instance of OpenLayers.Format
+     */
     initialize: function(options) {
         OpenLayers.Util.extend(this, options);
     },
 
     /**
-     * Read data from a string, and return a list of features. 
+     * Method: read
+     * Read data from a string, and return an object whose type depends on the
+     * subclass. 
      * 
-     * @param {string} data data to read/parse.
+     * Parameters:
+     * data - {string} Data to read/parse.
+     *
+     * Return:
+     * Depends on the subclass
      */
-     read: function(data) {
-         alert("Read not implemented.");
-     },
+    read: function(data) {
+        alert("Read not implemented.");
+    },
     
     /**
-     * Accept Feature Collection, and return a string. 
-     * 
-     * @param {Array} List of features to serialize into a string.
+     * Method: write
+     * Accept an object, and return a string. 
+     *
+     * Parameters:
+     * object - {Object} Object to be serialized
+     *
+     * Return:
+     * {String} A string representation of the object.
      */
-     write: function(features) {
-         alert("Write not implemented.");
-     },
+    write: function(object) {
+        alert("Write not implemented.");
+    },
 
-    /** @final @type String */
+    /**
+     * Constant: CLASS_NAME
+     * {String} OpenLayers.Format
+     */
     CLASS_NAME: "OpenLayers.Format"
 
 };