better docs for the Spherical namespace

lib/OpenLayers/Spherical.js

@@ -3,29 +3,32 @@
  * See http://svn.openlayers.org/trunk/openlayers/license.txt for the
  * full text of the license. */
 
-/**
- * @see http://www.movable-type.co.uk/scripts/latlong.html
- * @see http://code.google.com/apis/maps/documentation/javascript/reference.html#spherical
- */
-
-
 /**
  * Namespace: Spherical
+ * The OpenLayers.Spherical namespace includes utility functions for
+ * calculations on the basis of a spherical earth (ignoring ellipsoidal
+ * effects), which is accurate enough for most purposes.
+ *
+ * Relevant links:
+ * * http://www.movable-type.co.uk/scripts/latlong.html
+ * * http://code.google.com/apis/maps/documentation/javascript/reference.html#spherical
  */
+
 OpenLayers.Spherical = OpenLayers.Spherical || {};
 
-
 OpenLayers.Spherical.DEFAULT_RADIUS = 6378137;
 
-
 /**
  * APIFunction: computeDistanceBetween
  * Computes the distance between two LonLats.
  *
  * Parameters:
- * from   - {<OpenLayers.LonLat>}
+ * from   - {<OpenLayers.LonLat>} or {Object} Starting point. A LonLat or
- * to     - {<OpenLayers.LonLat>}
+ *          a JavaScript litteral with lon lat properties.
- * radius - {Float}
+ * to     - {<OpenLayers.LonLat>} or {Object} Ending point. A LonLat or a
+ *          JavaScript litteral with lon lat properties.
+ * radius - {Float} The radius. Optional. Defaults to the earth's
+ *          radius, i.e. 6378137 meters.
  *
  * Returns:
  * {Float} The distance in meters.
@@ -45,8 +48,10 @@ OpenLayers.Spherical.computeDistanceBetween = function(from, to, radius) {
  * Computes the heading from one LonLat to another LonLat.
  *
  * Parameters:
- * from - {<OpenLayers.LonLat>}
+ * from   - {<OpenLayers.LonLat>} or {Object} Starting point. A LonLat or
- * to   - {<OpenLayers.LonLat>}
+ *          a JavaScript litteral with lon lat properties.
+ * to     - {<OpenLayers.LonLat>} or {Object} Ending point. A LonLat or a
+ *          JavaScript litteral with lon lat properties.
  *
  * Returns:
  * {Float} The heading in degrees.