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

@@ -3,7 +3,8 @@
  * for the full text of the license. */
 
 /**
- * @class Renderer is the base class for all renderers.
+ * Class: Renderer 
+ * This is the base class for all renderers.
  *
  * This is based on a merger code written by Paul Spencer and Bertil Chapuis.
  * It is largely composed of virtual functions that are to be implemented
@@ -21,34 +22,48 @@
 OpenLayers.Renderer = OpenLayers.Class.create();
 OpenLayers.Renderer.prototype = 
 {
-    /** @type DOMElement */
+    /** 
+     * Property: container
+     * {DOMElement} 
+     */
     container: null,
     
-    /** @type OpenLayers.Bounds */
+    /** 
+     * Property: extent
+     * {<OpenLayers.Bounds>}
+     */
     extent: null,
     
-    /** @type OpenLayers.Size */
+    /** 
+     * Property: size
+     * {<OpenLayers.Size>} 
+     */
     size: null,
     
-    /** cache of current map resolution
-     * @type float */
+    /**
+     * Property: resolution
+     * {Float} cache of current map resolution
+     */
     resolution: null,
     
-    /** Reference to the map -- this is set in Vector's setMap()
-     * @type OpenLayers.Map */
+    /**
+     * Property: map  
+     * {<OpenLayers.Map>} Reference to the map -- this is set in Vector's setMap()
+     */
     map: null,
     
     /**
-     * @constructor
-     * 
-     * @param {String} containerID
+     * Constructor: OpenLayers.Renderer 
+     *
+     * Parameters:
+     * containerID - {<String>} 
      */
     initialize: function(containerID) {
         this.container = $(containerID);
     },
     
     /**
-     * 
+     * APIMethod: destroy
      */
     destroy: function() {
         this.container = null;
@@ -59,23 +74,26 @@ OpenLayers.Renderer.prototype =
     },
 
     /**
+     * APIMethod: supported
      * This should be overridden by specific subclasses
      * 
-     * @returns Whether or not the browser supports the VML renderer
-     * @type Boolean
+     * Returns:
+     * {Boolean} Whether or not the browser supports the renderer class
      */
     supported: function() {
         return false;
     },    
     
     /**
+     * Method: setExtent
      * Set the visible part of the layer.
      *
      * Resolution has probably changed, so we nullify the resolution 
      * cache (this.resolution) -- this way it will be re-computed when 
      * next it is needed.
      *
-     * @param {OpenLayers.Bounds} extent
+     * Parameters:
+     * extent - {<OpenLayers.Bounds>} 
      */
     setExtent: function(extent) {
         this.extent = extent.clone();
@@ -83,37 +101,42 @@ OpenLayers.Renderer.prototype =
     },
     
     /**
+     * Method: setSize
      * Sets the size of the drawing surface.
      * 
      * Resolution has probably changed, so we nullify the resolution 
      * cache (this.resolution) -- this way it will be re-computed when 
      * next it is needed.
      *
-     * @param {OpenLayers.Size} size
+     * Parameters:
+     * size - {<OpenLayers.Size>} 
      */
     setSize: function(size) {
         this.size = size.clone();
         this.resolution = null;
     },
     
-    /** Uses cached copy of resolution if available to minimize computing
+    /** 
+     * Method: getResolution
+     * Uses cached copy of resolution if available to minimize computing
      * 
-     * @returns The current map's resolution
-     * @type float
+     * Returns:
+     * The current map's resolution
      */
     getResolution: function() {
         this.resolution = this.resolution || this.map.getResolution();
         return this.resolution;
     },
     
-    /** 
+    /**
+     * Method: drawFeature
      * Draw the feature.  The optional style argument can be used
      * to override the feature's own style.  This method should only
      * be called from layer.drawFeature().
      *
-     * @param {OpenLayers.Feature.Vector} feature 
-     * @param {Object} style
-     * @private
+     * Parameters:
+     * feature - {<OpenLayers.Feature.Vector>} 
+     * style - {<Object>} 
      */
     drawFeature: function(feature, style) {
         if(style == null) {
@@ -124,45 +147,47 @@ OpenLayers.Renderer.prototype =
 
 
     /** 
-     * virtual function
+     * Method: drawGeometry
      * 
      * Draw a geometry.  This should only be called from the renderer itself.
      * Use layer.drawFeature() from outside the renderer.
+     * virtual function
      *
-     * @param geometry {OpenLayers.Geometry}
-     * @param style {Object}
-     * @param {String} featureId
-     * @private
+     * Parameters:
+     * geometry - {<OpenLayers.Geometry>} 
+     * style - {Object} 
+     * featureId - {<String>} 
      */
     drawGeometry: function(geometry, style, featureId) {},
         
     /**
-     * virtual function
-     *
-     * Clear all vectors from the renderer
-     * @private
+     * Method: clear
+     * Clear all vectors from the renderer.
+     * virtual function.
      */    
     clear: function() {},
 
     /**
-     * virtual function
-     * 
+     * Method: getFeatureIdFromEvent
      * Returns a feature id from an event on the renderer.  
      * How this happens is specific to the renderer.  This should be
      * called from layer.getFeatureFromEvent().
+     * Virtual function.
      * 
-     * @param evt {OpenLayers.Event}
+     * Parameters:
+     * evt - {<OpenLayers.Event>} 
      *
-     * @returns A feature id or null
-     * @type String
-     * @private
+     * Returns:
+     * {String} A feature id or null.
      */
     getFeatureIdFromEvent: function(evt) {},
     
     /**
+     * Method: eraseFeatures 
      * This is called by the layer to erase features
-     * @param {Array(OpenLayers.Feature.Vector)} features
-     * @private
+     * 
+     * Parameters:
+     * features - {Array(<OpenLayers.Feature.Vector>)} 
      */
     eraseFeatures: function(features) {
         if(!(features instanceof Array)) {
@@ -174,12 +199,12 @@ OpenLayers.Renderer.prototype =
     },
     
     /**
-     * virtual function
+     * Method: eraseGeometry
+     * Remove a geometry from the renderer (by id).
+     * virtual function.
      * 
-     * Remove a geometry from the renderer (by id)
-     * 
-     * @param geometry {OpenLayers.Geometry}
-     * @private
+     * Parameters:
+     * geometry - {<OpenLayers.Geometry>} 
      */
     eraseGeometry: function(geometry) {},