From 4cc1bf18993486d0bde9a6849994b639c064bd20 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89ric=20Lemoine?= <eric.lemoine@gmail.com>
Date: Thu, 9 Feb 2012 16:59:02 +0100
Subject: [PATCH] better docs for the Spherical namespace

---
 lib/OpenLayers/Spherical.js | 31 ++++++++++++++++++-------------
 1 file changed, 18 insertions(+), 13 deletions(-)

diff --git a/lib/OpenLayers/Spherical.js b/lib/OpenLayers/Spherical.js
index ed64c844f8..b19edc8939 100644
--- a/lib/OpenLayers/Spherical.js
+++ b/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>}
- * to     - {<OpenLayers.LonLat>}
- * radius - {Float}
+ * from   - {<OpenLayers.LonLat>} or {Object} Starting point. A LonLat or
+ *          a JavaScript litteral with lon lat properties.
+ * 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>}
- * to   - {<OpenLayers.LonLat>}
+ * from   - {<OpenLayers.LonLat>} or {Object} Starting point. A LonLat or
+ *          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.