From c0aa99162849a4e41f2aa9a89fe813a0a0d7dab6 Mon Sep 17 00:00:00 2001
From: Andrew Leung <andrew.leung@10gen.com>
Date: Wed, 18 Jul 2012 14:54:56 -0400
Subject: [PATCH 01/16] initial notes for geo operators

---
 source/reference/commands.txt  |  8 ++++++++
 source/reference/operators.txt | 13 +++++++++++++
 2 files changed, 21 insertions(+)

diff --git a/source/reference/commands.txt b/source/reference/commands.txt
index 896fa80a633..08deaf53d77 100644
--- a/source/reference/commands.txt
+++ b/source/reference/commands.txt
@@ -973,6 +973,14 @@ Geospatial Commands
                              by multiplying by the radius of the
                              Earth.
 
+   .. TODO add in box, circle, polygon options
+
+   :field box: box operator details
+
+   :field circle: circle operator details
+
+   :field polygon: polygon details
+
    .. read-lock, slave-ok
 
 .. dbcommand:: geoSearch
diff --git a/source/reference/operators.txt b/source/reference/operators.txt
index 679a112b41a..61e3cb16425 100644
--- a/source/reference/operators.txt
+++ b/source/reference/operators.txt
@@ -281,6 +281,8 @@ Geospatial
 
         db.collection.find( { location: { $within: { $box: [[100,0], [120,100]] } } } );
 
+     .. TODO fix this error ^^^ fads
+
      Here a box, ``[[100,120], [100,0]]`` describes the parameter
      for the query. As a minimum, you must specify the lower-left and
      upper-right corners of the box.
@@ -305,6 +307,17 @@ Geospatial
    although this is subject to the imprecision of floating point
    numbers.
 
+   .. TODO fill in bottom
+
+   .. operator:: $box
+
+
+   .. operator:: $circle
+
+
+   .. operator:: $polygon
+
+
 .. operator:: $uniqueDocs
 
    When using the :dbcommand:`geoNear`, if document contains more than

From 106296cd9fa1dea71d8e487beea67d1eaab93993 Mon Sep 17 00:00:00 2001
From: Andrew Leung <andrew.leung@10gen.com>
Date: Wed, 18 Jul 2012 15:35:40 -0400
Subject: [PATCH 02/16] initial draft with spherical notes in geoOperators

---
 source/reference/commands.txt  | 2 ++
 source/reference/operators.txt | 4 ++++
 2 files changed, 6 insertions(+)

diff --git a/source/reference/commands.txt b/source/reference/commands.txt
index 08deaf53d77..3013f8854c8 100644
--- a/source/reference/commands.txt
+++ b/source/reference/commands.txt
@@ -981,6 +981,8 @@ Geospatial Commands
 
    :field polygon: polygon details
 
+   :field spherical: spherical details
+
    .. read-lock, slave-ok
 
 .. dbcommand:: geoSearch
diff --git a/source/reference/operators.txt b/source/reference/operators.txt
index 61e3cb16425..e43d4019fe9 100644
--- a/source/reference/operators.txt
+++ b/source/reference/operators.txt
@@ -318,6 +318,10 @@ Geospatial
    .. operator:: $polygon
 
 
+.. operator:: $nearSphere
+
+.. operator:: $centerSphere
+
 .. operator:: $uniqueDocs
 
    When using the :dbcommand:`geoNear`, if document contains more than

From d1d3c4e97d579f8fd1b9528beef1fbf44e90dfca Mon Sep 17 00:00:00 2001
From: Andrew Leung <andrew.leung@10gen.com>
Date: Wed, 18 Jul 2012 17:16:34 -0400
Subject: [PATCH 03/16] drafting  and  ops

---
 source/reference/operators.txt | 28 +++++++++++++++++++++++++---
 1 file changed, 25 insertions(+), 3 deletions(-)

diff --git a/source/reference/operators.txt b/source/reference/operators.txt
index e43d4019fe9..6ac0bff8cfb 100644
--- a/source/reference/operators.txt
+++ b/source/reference/operators.txt
@@ -281,8 +281,6 @@ Geospatial
 
         db.collection.find( { location: { $within: { $box: [[100,0], [120,100]] } } } );
 
-     .. TODO fix this error ^^^ fads
-
      Here a box, ``[[100,120], [100,0]]`` describes the parameter
      for the query. As a minimum, you must specify the lower-left and
      upper-right corners of the box.
@@ -298,7 +296,7 @@ Geospatial
 
      .. code-block:: javascript
 
-        db.collection.find( { location: { $within: { $box: [[100,120], [100,100], [120,100], [240,200]] } } } );
+        db.collection.find( { location: { $within: { $polygon: [[100,120], [100,100], [120,100], [240,200]] } } } );
 
      The last point of a polygon is implicitly connected to the first
      point.
@@ -311,9 +309,26 @@ Geospatial
 
    .. operator:: $box
 
+      :operator:`$box` is a box shape operator used with :operator:`$within` to
+      perform rectangular bounded searches on geospatial data.
+
+      To specify the :operator:`$box` shape, you need to declare the
+      bottom left and top right corners. 
+
+      Point 1 = [a,b] point 2 = [c,d]
+
+      .. code-block:: javascript
+
+         db.collection.find( { loc: { "$within": {
 
    .. operator:: $circle
 
+      :operator:`$circle` is a circle shape operator used with
+      :operator:`$within` operator to perform circular bounded
+      searches on geospatial data.
+
+      To specify the :operator:`$circle` shape, you need to declare
+      the center point and radius of the circle. 
 
    .. operator:: $polygon
 
@@ -322,6 +337,13 @@ Geospatial
 
 .. operator:: $centerSphere
 
+.. operator:: $distanceMultiplier
+
+.. TODO verify above operator. does it exist? (i.e. I think it does
+.. for geoNear...)
+
+.. TODO put $uniqueDocs in the geonear command ref too? 
+
 .. operator:: $uniqueDocs
 
    When using the :dbcommand:`geoNear`, if document contains more than

From cf9729919dc56397401240b1b4f99e3cd5122bf3 Mon Sep 17 00:00:00 2001
From: Andrew Leung <andrew.leung@10gen.com>
Date: Thu, 26 Jul 2012 14:20:58 -0400
Subject: [PATCH 04/16] saving some progress...

---
 source/reference/operators.txt | 51 +++++++++++++++++++++++++++++-----
 1 file changed, 44 insertions(+), 7 deletions(-)

diff --git a/source/reference/operators.txt b/source/reference/operators.txt
index 6ac0bff8cfb..2046b8da54a 100644
--- a/source/reference/operators.txt
+++ b/source/reference/operators.txt
@@ -309,36 +309,73 @@ Geospatial
 
    .. operator:: $box
 
-      :operator:`$box` is a box shape operator used with :operator:`$within` to
-      perform rectangular bounded searches on geospatial data.
+      :operator:`$box` option is used with the :operator:`$within`
+      option to perform rectangular bounded searches on geospatial
+      data. This is useful for searching within a rectangular area in
+      a geospatial dataset such as a specific neighborhood.
 
       To specify the :operator:`$box` shape, you need to declare the
-      bottom left and top right corners. 
+      bottom left and top right corners, preferrably in an array object. 
 
       Point 1 = [a,b] point 2 = [c,d]
 
       .. code-block:: javascript
 
-         db.collection.find( { loc: { "$within": {
+         db.collection.find( { loc: { $within: { $box: [a,b], [c,d] } } } )
 
    .. operator:: $circle
 
-      :operator:`$circle` is a circle shape operator used with
-      :operator:`$within` operator to perform circular bounded
-      searches on geospatial data.
+      The :operator:`$circle` option is used with the
+      :operator:`$within` option to perform circular bounded
+      searches on geospatial data. :operator:`$circle` provides
+      greater fidelity in searching a specific area than
+      :operator:`$near` or :operator:`maxDistance` options.
 
       To specify the :operator:`$circle` shape, you need to declare
       the center point and radius of the circle. 
 
+      .. code-block:: javascript
+
+         db.collection.find( { loc: { $within: { $circle: [a,b], radius } } } )
+
    .. operator:: $polygon
 
+      The :operator:`$polygon` option is used with the
+      :operator:`$within` option to provide polygonal bounded searches
+      on geospatial data. :operator:`$polygon` option is useful for
+      searching within specific areas that correspond to irregularly
+      shaped areas such as a dense urban neighborhood.
+
+      To specify the :operator:`$polygon` option, you need to declare
+      the points of the polygon. The last point will automatically be
+      connected to the first point.
+
+      .. code-block:: javascript
+
+         db.collection.find( { loc: { $within: { $polygon:
+	                                         [a,b], [c,d], [e,f] } } } )
 
 .. operator:: $nearSphere
 
+   The :operator:`$nearSphere` option allows you to perform `$near`
+   searches using spherical representation system. 
+
+   .. code-block:: javascript
+
+      db.collection.find( { loc: { $nearSphere: [a,b] } } )
+
 .. operator:: $centerSphere
 
+   The :operator:`$centerSphere` option 
+
+   .. code-block:: javascript
+
+      db.collection.find( { loc: { $centerSphere: { [a,b], c } } } )
+
 .. operator:: $distanceMultiplier
 
+
+
 .. TODO verify above operator. does it exist? (i.e. I think it does
 .. for geoNear...)
 

From 3b0e8adfe73d50f790865e37e2f806edd1736828 Mon Sep 17 00:00:00 2001
From: Andrew Leung <andrew.leung@10gen.com>
Date: Thu, 26 Jul 2012 18:32:46 -0400
Subject: [PATCH 05/16] filling out more operators

---
 source/reference/operators.txt | 67 ++++++++++++++++++++++------------
 1 file changed, 43 insertions(+), 24 deletions(-)

diff --git a/source/reference/operators.txt b/source/reference/operators.txt
index 2046b8da54a..a048bba6b40 100644
--- a/source/reference/operators.txt
+++ b/source/reference/operators.txt
@@ -303,9 +303,7 @@ Geospatial
 
    All shapes include the border of the shape as part of the shape,
    although this is subject to the imprecision of floating point
-   numbers.
-
-   .. TODO fill in bottom
+   calculations.
 
    .. operator:: $box
 
@@ -315,28 +313,36 @@ Geospatial
       a geospatial dataset such as a specific neighborhood.
 
       To specify the :operator:`$box` shape, you need to declare the
-      bottom left and top right corners, preferrably in an array object. 
-
-      Point 1 = [a,b] point 2 = [c,d]
+      bottom left and top right corners, in an array object. 
 
       .. code-block:: javascript
 
-         db.collection.find( { loc: { $within: { $box: [a,b], [c,d] } } } )
+         db.collection.find( { loc: { $within: { $box: [ [0,0],
+                                                         [100,100] ] } } } )
+
+      This will return all the documents that are within the box: [0,0],
+      [0,100], [100,0], and [100,100]. All points that lie on the
+      borders will be included in the result.
 
-   .. operator:: $circle
+   .. operator:: $center
 
-      The :operator:`$circle` option is used with the
+      The :operator:`$center` option is used with the
       :operator:`$within` option to perform circular bounded
-      searches on geospatial data. :operator:`$circle` provides
+      searches on geospatial data. :operator:`$center` provides
       greater fidelity in searching a specific area than
       :operator:`$near` or :operator:`maxDistance` options.
 
-      To specify the :operator:`$circle` shape, you need to declare
+      To specify the :operator:`$center` shape, you need to declare
       the center point and radius of the circle. 
 
       .. code-block:: javascript
 
-         db.collection.find( { loc: { $within: { $circle: [a,b], radius } } } )
+         db.collection.find( { loc: { $within: { $center: [ [0,0], 100 ] } } } )
+
+      This will return all the documents that are 100 longitude or
+      latitude around point [0,0]. All documents that lie on the
+      boundary of this circle will be included, but some may not due
+      to imprecision of floating point calculation.
 
    .. operator:: $polygon
 
@@ -352,32 +358,45 @@ Geospatial
 
       .. code-block:: javascript
 
-         db.collection.find( { loc: { $within: { $polygon:
-	                                         [a,b], [c,d], [e,f] } } } )
+         db.collection.find( { loc: { $within: { $polygon: [ [0,0], [3,6], [6,0]  ] } } } )
+
+      This will return all the documents that are within the polygon
+      [0,0], [3,6], [6,0]. All documents that lie on the boundaries
+      will be included, but some may not due to imprecision of
+      floating point calculations.
 
 .. operator:: $nearSphere
 
-   The :operator:`$nearSphere` option allows you to perform `$near`
-   searches using spherical representation system. 
+   The :operator:`$nearSphere` option performs `$near` searches using
+   spherical representation system. Use :operator:`$nearSphere` with
+   the ``$maxDistance`` option to utilize spherical
+   representation. Remember that distances must be converted to
+   radians when using spherical operators.
 
    .. code-block:: javascript
 
-      db.collection.find( { loc: { $nearSphere: [a,b] } } )
+      db.collection.find( { loc: { $nearSphere: [0,0],
+                                   $maxDistance: 10 / 3959 } } )
 
-.. operator:: $centerSphere
+   This will return all documents 10 mile near [0,0] using a spherical
+   representation system.
 
-   The :operator:`$centerSphere` option 
+.. TODO fill in this section
 
-   .. code-block:: javascript
+.. operator:: $centerSphere
 
-      db.collection.find( { loc: { $centerSphere: { [a,b], c } } } )
+   The :operator:`$centerSphere` option returns all the documents that
+   are within a certain radius from a point.
 
-.. operator:: $distanceMultiplier
+   .. code-block:: javascript
 
+      db.collection.find( { loc: { $centerSphere: { [0,0], 10 / 3959 }
+      } } )
 
+   This will return all documents within a 10 mile radius from [0,0]
+   using a spherical representation system.
 
-.. TODO verify above operator. does it exist? (i.e. I think it does
-.. for geoNear...)
+.. operator:: $distanceMultiplier
 
 .. TODO put $uniqueDocs in the geonear command ref too? 
 

From 7386d1c63e055a1cdb1110a984f9cab0e5e47741 Mon Sep 17 00:00:00 2001
From: Andrew Leung <andrew.leung@10gen.com>
Date: Fri, 27 Jul 2012 14:39:42 -0400
Subject: [PATCH 06/16] operators update...

---
 source/reference/operators.txt | 107 +++++++++------------------------
 1 file changed, 30 insertions(+), 77 deletions(-)

diff --git a/source/reference/operators.txt b/source/reference/operators.txt
index a048bba6b40..a77716b1f00 100644
--- a/source/reference/operators.txt
+++ b/source/reference/operators.txt
@@ -274,46 +274,11 @@ Geospatial
    :operator:`$within` command supports three shapes. These shapes and the
    relevant expressions follow:
 
-   - Rectangles. Use the :operator:`$box` shape, consider the following
-     variable and :operator:`$within` document:
-
-     .. code-block:: javascript
-
-        db.collection.find( { location: { $within: { $box: [[100,0], [120,100]] } } } );
-
-     Here a box, ``[[100,120], [100,0]]`` describes the parameter
-     for the query. As a minimum, you must specify the lower-left and
-     upper-right corners of the box.
-
-   - Circles. Specify circles in the following form:
-
-     .. code-block:: javascript
-
-        db.collection.find( { location: { $within: { $circle: [ center, radius } } } );
-
-   - Polygons. Specify polygons with an array of points. See the
-     following example:
-
-     .. code-block:: javascript
-
-        db.collection.find( { location: { $within: { $polygon: [[100,120], [100,100], [120,100], [240,200]] } } } );
-
-     The last point of a polygon is implicitly connected to the first
-     point.
-
-   All shapes include the border of the shape as part of the shape,
-   although this is subject to the imprecision of floating point
-   calculations.
-
    .. operator:: $box
 
-      :operator:`$box` option is used with the :operator:`$within`
-      option to perform rectangular bounded searches on geospatial
-      data. This is useful for searching within a rectangular area in
-      a geospatial dataset such as a specific neighborhood.
-
       To specify the :operator:`$box` shape, you need to declare the
-      bottom left and top right corners, in an array object. 
+      bottom left and top right corners of the box in an array
+      object. Consider the following example:
 
       .. code-block:: javascript
 
@@ -321,68 +286,55 @@ Geospatial
                                                          [100,100] ] } } } )
 
       This will return all the documents that are within the box: [0,0],
-      [0,100], [100,0], and [100,100]. All points that lie on the
-      borders will be included in the result.
+      [0,100], [100,0], and [100,100].
 
    .. operator:: $center
 
-      The :operator:`$center` option is used with the
-      :operator:`$within` option to perform circular bounded
-      searches on geospatial data. :operator:`$center` provides
-      greater fidelity in searching a specific area than
-      :operator:`$near` or :operator:`maxDistance` options.
-
-      To specify the :operator:`$center` shape, you need to declare
-      the center point and radius of the circle. 
+      To specify the :operator:`$center` shape in the following form:
 
       .. code-block:: javascript
 
-         db.collection.find( { loc: { $within: { $center: [ [0,0], 100 ] } } } )
+         db.collection.find( { location: { $within: { $center: [ [0,0], 10 } } } );
+
+      :operator:`$center` provides greater fidelity in searching a
+      specific area than :operator:`$near` or :operator:`maxDistance`
+      options.
 
       This will return all the documents that are 100 longitude or
-      latitude around point [0,0]. All documents that lie on the
-      boundary of this circle will be included, but some may not due
-      to imprecision of floating point calculation.
+      latitude around point [0,0].
 
    .. operator:: $polygon
 
-      The :operator:`$polygon` option is used with the
-      :operator:`$within` option to provide polygonal bounded searches
-      on geospatial data. :operator:`$polygon` option is useful for
-      searching within specific areas that correspond to irregularly
-      shaped areas such as a dense urban neighborhood.
+      To specify an arbitrary :operator:`$polygon` with an array of
+      points. The last point is always implicitly connected to the
+      first point. See the following example:
+
+     .. code-block:: javascript
 
-      To specify the :operator:`$polygon` option, you need to declare
-      the points of the polygon. The last point will automatically be
-      connected to the first point.
+        db.collection.find( { loc: { $within: { $polygon: [ [0,0], [3,6], [6,0]  ] } } } )
 
-      .. code-block:: javascript
+     This will return all the documents that are within the polygon
+     [0,0], [3,6], [6,0]. Here, this is an equilateral triangle. This
+     is useful for searching within specific areas that correspond to
+     irregularly shaped areas such as a dense urban neighborhood.
 
-         db.collection.find( { loc: { $within: { $polygon: [ [0,0], [3,6], [6,0]  ] } } } )
 
-      This will return all the documents that are within the polygon
-      [0,0], [3,6], [6,0]. All documents that lie on the boundaries
-      will be included, but some may not due to imprecision of
-      floating point calculations.
+   All shapes include the border of the shape as part of the shape,
+   although this is subject to the imprecision of floating point
+   calculations.
 
 .. operator:: $nearSphere
 
-   The :operator:`$nearSphere` option performs `$near` searches using
-   spherical representation system. Use :operator:`$nearSphere` with
-   the ``$maxDistance`` option to utilize spherical
-   representation. Remember that distances must be converted to
-   radians when using spherical operators.
+   The :operator:`$nearSphere` option performs :operator:`$near`
+   searches using spherical representation system.
 
    .. code-block:: javascript
 
-      db.collection.find( { loc: { $nearSphere: [0,0],
-                                   $maxDistance: 10 / 3959 } } )
+      db.collection.find( { loc: { $nearSphere: [0,0] } } )
 
-   This will return all documents 10 mile near [0,0] using a spherical
+   This will return all documents near [0,0] using a spherical
    representation system.
 
-.. TODO fill in this section
-
 .. operator:: $centerSphere
 
    The :operator:`$centerSphere` option returns all the documents that
@@ -390,14 +342,15 @@ Geospatial
 
    .. code-block:: javascript
 
-      db.collection.find( { loc: { $centerSphere: { [0,0], 10 / 3959 }
-      } } )
+      db.collection.find( { loc: { $centerSphere: { [0,0], 10 / 3959 } } } )
 
    This will return all documents within a 10 mile radius from [0,0]
    using a spherical representation system.
 
 .. operator:: $distanceMultiplier
 
+   
+
 .. TODO put $uniqueDocs in the geonear command ref too? 
 
 .. operator:: $uniqueDocs

From b58c916d81e360ae34108d902027f866776e4309 Mon Sep 17 00:00:00 2001
From: Andrew Leung <andrew.leung@10gen.com>
Date: Fri, 27 Jul 2012 14:40:13 -0400
Subject: [PATCH 07/16] operators update...

---
 source/reference/operators.txt | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/source/reference/operators.txt b/source/reference/operators.txt
index a77716b1f00..fc2fb4352c5 100644
--- a/source/reference/operators.txt
+++ b/source/reference/operators.txt
@@ -325,15 +325,15 @@ Geospatial
 
 .. operator:: $nearSphere
 
-   The :operator:`$nearSphere` option performs :operator:`$near`
-   searches using spherical representation system.
+   The :operator:`$nearSphere` option returns all documents near a
+   point using spherical representation system to calculate distances.
 
    .. code-block:: javascript
 
       db.collection.find( { loc: { $nearSphere: [0,0] } } )
 
    This will return all documents near [0,0] using a spherical
-   representation system.
+   representation system to calculate distances from [0,0].
 
 .. operator:: $centerSphere
 
@@ -345,7 +345,8 @@ Geospatial
       db.collection.find( { loc: { $centerSphere: { [0,0], 10 / 3959 } } } )
 
    This will return all documents within a 10 mile radius from [0,0]
-   using a spherical representation system.
+   using a spherical representation system to calculate distances from
+   [0,0].
 
 .. operator:: $distanceMultiplier
 

From 2a974964bf1bc7dd347c96aec8437ec989440667 Mon Sep 17 00:00:00 2001
From: Andrew Leung <andrew.leung@10gen.com>
Date: Fri, 27 Jul 2012 16:53:23 -0400
Subject: [PATCH 08/16] draft finished - geo operators documented.

---
 source/reference/operators.txt | 104 ++++++++++++++++++++-------------
 1 file changed, 63 insertions(+), 41 deletions(-)

diff --git a/source/reference/operators.txt b/source/reference/operators.txt
index fc2fb4352c5..ab4fd527c10 100644
--- a/source/reference/operators.txt
+++ b/source/reference/operators.txt
@@ -271,53 +271,62 @@ Geospatial
       db.collection.find( { location: { $within: { shape } } } );
 
    Replace ``{ shape }`` with a document that describes a shape. The
-   :operator:`$within` command supports three shapes. These shapes and the
-   relevant expressions follow:
+   :operator:`$within` command supports three basic shape types. These
+   shapes and the relevant expressions follow:
 
    .. operator:: $box
 
-      To specify the :operator:`$box` shape, you need to declare the
-      bottom left and top right corners of the box in an array
+      This specifies a box or rectangle shape for :operator:`$box`. To
+      use the :operator:`$box` shape, you need to declare the bottom
+      left and top right corners of the box in an array
       object. Consider the following example:
 
       .. code-block:: javascript
 
-         db.collection.find( { loc: { $within: { $box: [ [0,0],
-                                                         [100,100] ] } } } )
+         db.collection.find( { loc: { $within: { $box: [ [0,0], [100,100] ] } } } )
 
-      This will return all the documents that are within the box: [0,0],
-      [0,100], [100,0], and [100,100].
+      This will return all the documents that are within the box
+      having points: [0,0], [0,100], [100,0], and [100,100].
 
    .. operator:: $center
 
-      To specify the :operator:`$center` shape in the following form:
+      This specifies a circle shape for :operator:`$within`. To use
+      the :operator:`$center` option, you need to specify the center
+      point and the radius of the circle. Considering the following
+      example:
 
       .. code-block:: javascript
 
          db.collection.find( { location: { $within: { $center: [ [0,0], 10 } } } );
 
+      This will return all the documents that are 10 around point
+      [0,0].
+
+      .. note::
+
+         Distances in queries are the same units as the location
+         index.
+
       :operator:`$center` provides greater fidelity in searching a
-      specific area than :operator:`$near` or :operator:`maxDistance`
+      specific area than :operator:`$near` with :operator:`maxDistance`
       options.
 
-      This will return all the documents that are 100 longitude or
-      latitude around point [0,0].
-
    .. operator:: $polygon
 
-      To specify an arbitrary :operator:`$polygon` with an array of
+      This specifies a polygon shape for :operator:`$within`. You can
+      specify an arbitrary number of points to create an multipoint
+      polygon. To specify a :operator:`$polygon` shape, use an array of
       points. The last point is always implicitly connected to the
       first point. See the following example:
 
-     .. code-block:: javascript
-
-        db.collection.find( { loc: { $within: { $polygon: [ [0,0], [3,6], [6,0]  ] } } } )
+      .. code-block:: javascript
 
-     This will return all the documents that are within the polygon
-     [0,0], [3,6], [6,0]. Here, this is an equilateral triangle. This
-     is useful for searching within specific areas that correspond to
-     irregularly shaped areas such as a dense urban neighborhood.
+         db.collection.find( { loc: { $within: { $polygon: [ [0,0], [3,6], [6,0]  ] } } } )
 
+      This will return all the documents that are within the polygon
+      [0,0], [3,6], [6,0]. This is useful for searching within
+      specific areas that correspond to irregularly shaped areas such
+      as a dense urban neighborhood.
 
    All shapes include the border of the shape as part of the shape,
    although this is subject to the imprecision of floating point
@@ -338,7 +347,8 @@ Geospatial
 .. operator:: $centerSphere
 
    The :operator:`$centerSphere` option returns all the documents that
-   are within a certain radius from a point.
+   are within a certain radius from a point. Remember that all
+   distances, like the radius, have to be converted to radians.
 
    .. code-block:: javascript
 
@@ -348,34 +358,46 @@ Geospatial
    using a spherical representation system to calculate distances from
    [0,0].
 
-.. operator:: $distanceMultiplier
-
-   
+   .. note::
 
-.. TODO put $uniqueDocs in the geonear command ref too? 
+      For spherical queries, you must convert distances to radians for
+      proper results.
 
 .. operator:: $uniqueDocs
 
-   When using the :dbcommand:`geoNear`, if document contains more than
-   one field with coordinate values, MongoDB will return the same
-   document multiple times. When using the :operator:`$within`,
-   however, MongoDB provides opposite behavior: if a document contains
-   more than one field with coordinate values, MongoDB will only
-   return the document once.
+   The :operator:`$uniqueDocs` operator overrides default behaviors in
+   the :dbcommand:`geoNear` and :func:`find() <db.collection.find()>`
+   method with :operator:`$within` when there are multiple location
+   fields in documents (i.e. embedded in an array) 
 
-   The :operator:`$uniqueDocs` operator overrides these default
-   behaviors.
+   When using the :operator:`$within`, if a document contains more
+   than one field with location coordinates, MongoDB will only return the
+   document once.
 
    By specifying ``$uniqueDocs: false`` in a :operator:`$within`
-   query, will cause the query to return a single document multiple
-   times if there is more than one match.
+   query, it will cause the query to return a single document multiple
+   times, even if there is more than one match.
 
-   By contrast, if you specify ``uniqueDocs: true`` as an option to
-   the a :dbcommand:`geoNear` command, then :dbcommand:`geoNear` only
-   returns a single document even if there are multiple matches.
+   .. code-block:: javascript
+
+      db.places.find( { loc : { $within : { $center : [[0.5, 0.5], 20], $uniqueDocs : true } } } )
+      
+   When using the :dbcommand:`geoNear` command, if a document contains
+   more than one field with coordinate values, MongoDB will return the
+   same document multiple times.
+
+   If you specify ``uniqueDocs: true`` as an option to the
+   :dbcommand:`geoNear` command, then MongoDB will only return a
+   single document, even if there are multiple matches.
+
+   .. code-block:: javascript
+
+      db.runCommand( { geoNear : "collection" , near : [0,0], num : 10, uniqueDocs : false } )
+
+   .. note::
 
-   You cannot specify :operator:`$uniqueDocs` with :operator:`$near`
-   or haystack queries.
+      You cannot specify :operator:`$uniqueDocs` with
+      :operator:`$near` or haystack queries.
 
 .. index:: query selectors; logical
 .. _query-selectors-logical:

From 20560e5e190722b35d2375fdd96a199e2613aa24 Mon Sep 17 00:00:00 2001
From: Andrew Leung <andrew.leung@10gen.com>
Date: Tue, 31 Jul 2012 17:22:22 -0400
Subject: [PATCH 09/16] adding in command description for geo Operators. also
 updating uniqueDocs

---
 draft/applications/geospatial-indexes.txt |  8 ++-
 source/reference/commands.txt             | 24 +++++--
 source/reference/operators.txt            | 87 ++++++++++++-----------
 3 files changed, 69 insertions(+), 50 deletions(-)

diff --git a/draft/applications/geospatial-indexes.txt b/draft/applications/geospatial-indexes.txt
index 6057aa77958..20e93662a87 100644
--- a/draft/applications/geospatial-indexes.txt
+++ b/draft/applications/geospatial-indexes.txt
@@ -208,8 +208,8 @@ Circles
 
 To return results within the :ref:`bounds <geospatial-query-bounded>`
 of a circle, you must specify the center and the radius of the circle,
-using the :operator:`$within` operator and the :operator:`$circle`
-option. Consider the following prototype query:
+using the :operator:`$within` operator and the :operator:`$center`
+operator. Consider the following prototype query:
 
 .. code-block:: javascript
 
@@ -364,6 +364,8 @@ their distance from the ``[ -74, 40.74 ]`` point.
 
 .. TODO add in distanceMultiplier description
 
+.. _geospatial-query-multi-location:
+
 Multi-location Documents
 ------------------------
 
@@ -429,4 +431,6 @@ in the following example:
 
    db.records.ensureIndex( { "addresses.loc": "2d" } )
 
+.. TODO include: includeLocs field
+
 .. includes:: /includes/geospatial-sharding.rst
diff --git a/source/reference/commands.txt b/source/reference/commands.txt
index 3013f8854c8..1535e066ffb 100644
--- a/source/reference/commands.txt
+++ b/source/reference/commands.txt
@@ -948,8 +948,8 @@ Geospatial Commands
 
    Here, :dbcommand:`geoNear` returns the 10 items nearest to the
    coordinates ``[50,50]`` in the collection named
-   ``places``. `geoNear` provides the following options (specify all
-   distances in the same units as the document coordinate system:)
+   ``places``. The :dbcommand:`geoNear` command provides the following options (specify all
+   distances in the same units as the document coordinate system.)
 
    :field near: Takes the coordinates (e.g. ``[ x, y ]``) to use as
                 the center of a geospatial query.
@@ -973,15 +973,25 @@ Geospatial Commands
                              by multiplying by the radius of the
                              Earth.
 
-   .. TODO add in box, circle, polygon options
+   :field box: Specifies a rectangle or box shape to query within. To
+               specify the bounds of the rectangle, you must specify
+               the bottom left and top right corners of the rectangle
+               in an array object.
 
-   :field box: box operator details
+   .. TODO is this really 'circle'??? 
 
-   :field circle: circle operator details
+   :field circle: Specifies a circular shape to query within. To
+                  specify the bounds of the circle, you must specify
+                  the center point in an array and the radius of the circle.
 
-   :field polygon: polygon details
+   :field polygon: Specifies a polygon shape to query within. To
+                   specify the bounds of the polygon, you must specify
+                   an array of points. The last point will
+                   automatically be joined with the first one.
 
-   :field spherical: spherical details
+   :option boolean spherical: Specifies whether to use spherical
+                              coordinate system to calculate
+                              distances.
 
    .. read-lock, slave-ok
 
diff --git a/source/reference/operators.txt b/source/reference/operators.txt
index ab4fd527c10..e6d07b1f81a 100644
--- a/source/reference/operators.txt
+++ b/source/reference/operators.txt
@@ -271,15 +271,16 @@ Geospatial
       db.collection.find( { location: { $within: { shape } } } );
 
    Replace ``{ shape }`` with a document that describes a shape. The
-   :operator:`$within` command supports three basic shape types. These
+   :operator:`$within` operator supports three basic shape types. These
    shapes and the relevant expressions follow:
 
    .. operator:: $box
 
-      This specifies a box or rectangle shape for :operator:`$box`. To
-      use the :operator:`$box` shape, you need to declare the bottom
-      left and top right corners of the box in an array
-      object. Consider the following example:
+      The :operator:`$box` operator specifies a box or rectangle shape
+      for the :operator:`$within` operator. To use the
+      :operator:`$box` operator, you must specify the bottom left and
+      top right corners of the rectangle in an array object. Consider the
+      following example:
 
       .. code-block:: javascript
 
@@ -290,34 +291,31 @@ Geospatial
 
    .. operator:: $center
 
-      This specifies a circle shape for :operator:`$within`. To use
-      the :operator:`$center` option, you need to specify the center
-      point and the radius of the circle. Considering the following
-      example:
+      This specifies a circle shape for the :operator:`$within`
+      operators. To define the bounds of a query using
+      :operator:`$center`, you must specify:
 
-      .. code-block:: javascript
+         - the center point, and
 
-         db.collection.find( { location: { $within: { $center: [ [0,0], 10 } } } );
+	 - the radius
 
-      This will return all the documents that are 10 around point
-      [0,0].
+      Considering the following example:
 
-      .. note::
+      .. code-block:: javascript
 
-         Distances in queries are the same units as the location
-         index.
+         db.collection.find( { location: { $within: { $center: [ [0,0], 10 } } } );
 
-      :operator:`$center` provides greater fidelity in searching a
-      specific area than :operator:`$near` with :operator:`maxDistance`
-      options.
+      The above command returns all the documents that fall within a
+      10 unit radius of the point [0,0].
 
    .. operator:: $polygon
 
-      This specifies a polygon shape for :operator:`$within`. You can
-      specify an arbitrary number of points to create an multipoint
-      polygon. To specify a :operator:`$polygon` shape, use an array of
-      points. The last point is always implicitly connected to the
-      first point. See the following example:
+      The :operator:`$polygon` operator specifies a polygon shape for
+      the :operator:`$within` operator. To define the bounds of the
+      polygon, you must specify an array of coordinate points. The
+      last point is always implicitly connected to the first
+      point. You can specify an arbitrary number of points to create
+      an multipoint polygon. See the following example:
 
       .. code-block:: javascript
 
@@ -334,7 +332,7 @@ Geospatial
 
 .. operator:: $nearSphere
 
-   The :operator:`$nearSphere` option returns all documents near a
+   The :operator:`$nearSphere` operator returns all documents near a
    point using spherical representation system to calculate distances.
 
    .. code-block:: javascript
@@ -346,17 +344,20 @@ Geospatial
 
 .. operator:: $centerSphere
 
-   The :operator:`$centerSphere` option returns all the documents that
-   are within a certain radius from a point. Remember that all
-   distances, like the radius, have to be converted to radians.
+   The :operator:`$centerSphere` operator returns all the documents that
+   are within a certain radius from a point using spherical
+   representation. To define the bounds of the :operator:`$centerSphere` operator,
+   you must specify the center point and the radius.
+
+   Considering the following example:
 
    .. code-block:: javascript
 
       db.collection.find( { loc: { $centerSphere: { [0,0], 10 / 3959 } } } )
 
-   This will return all documents within a 10 mile radius from [0,0]
-   using a spherical representation system to calculate distances from
-   [0,0].
+   This will return all documents with a coordinate pair that is
+   within a 10 mile radius of [0,0] using a spherical representation
+   system to calculate distances from [0,0].
 
    .. note::
 
@@ -365,18 +366,19 @@ Geospatial
 
 .. operator:: $uniqueDocs
 
-   The :operator:`$uniqueDocs` operator overrides default behaviors in
-   the :dbcommand:`geoNear` and :func:`find() <db.collection.find()>`
-   method with :operator:`$within` when there are multiple location
-   fields in documents (i.e. embedded in an array) 
+   The :operator:`$uniqueDocs` operator overrides default query
+   behavior when :ref:`multiple location documents
+   <geospatial-query-multi-location>` are used.
 
-   When using the :operator:`$within`, if a document contains more
-   than one field with location coordinates, MongoDB will only return the
-   document once.
+   .. TODO check this functionality again.
 
-   By specifying ``$uniqueDocs: false`` in a :operator:`$within`
-   query, it will cause the query to return a single document multiple
-   times, even if there is more than one match.
+   When querying multiple location documents using the
+   :operator:`$within` operator, MongoDB will return matching documents
+   once, even if there are multiple matches in the location fields.
+
+   By specifying ``$uniqueDocs: false`` in the :operator:`$within`
+   operator, matching documents may be returned multiple times if
+   there are multiple matches.
 
    .. code-block:: javascript
 
@@ -399,6 +401,9 @@ Geospatial
       You cannot specify :operator:`$uniqueDocs` with
       :operator:`$near` or haystack queries.
 
+
+
+
 .. index:: query selectors; logical
 .. _query-selectors-logical:
 

From a6181f022d1733e777413f04af8948beb088dcf2 Mon Sep 17 00:00:00 2001
From: Andrew Leung <andrew.leung@10gen.com>
Date: Wed, 1 Aug 2012 14:51:06 -0400
Subject: [PATCH 10/16] updating geoOperators - DOCS-151

---
 source/reference/commands.txt  | 58 +++++++++++-------------
 source/reference/operators.txt | 82 ++++++++++++++++------------------
 2 files changed, 64 insertions(+), 76 deletions(-)

diff --git a/source/reference/commands.txt b/source/reference/commands.txt
index 1535e066ffb..9cd685d8e83 100644
--- a/source/reference/commands.txt
+++ b/source/reference/commands.txt
@@ -937,19 +937,18 @@ Geospatial Commands
 .. dbcommand:: geoNear
 
    The :dbcommand:`geoNear` command provides an alternative to the
-   :dbcommand:`$near` operator. In addition to the
-   functionality of :operator:`$near`, :dbcommand:`geoNear` returns the distance of
-   each item from the specified point along with additional diagnostic
-   information. For example:
+   :func:`db.collection.find()` method with :dbcommand:`$near`
+   operator. In addition to the functionality of :operator:`$near`,
+   :dbcommand:`geoNear` returns the distance of each item from the
+   specified point along with additional diagnostic information. The
+   following :dbcommand:`geoNear` example returns the 10 items nearest
+   to the coordinates ``[50,50]`` in the collection named ``places``.
 
    .. code-block:: javascript
 
       { geoNear : "places" , near : [50,50], num : 10 }
 
-   Here, :dbcommand:`geoNear` returns the 10 items nearest to the
-   coordinates ``[50,50]`` in the collection named
-   ``places``. The :dbcommand:`geoNear` command provides the following options (specify all
-   distances in the same units as the document coordinate system.)
+   The :dbcommand:`geoNear` command provides the following options:
 
    :field near: Takes the coordinates (e.g. ``[ x, y ]``) to use as
                 the center of a geospatial query.
@@ -965,33 +964,14 @@ Geospatial Commands
                  information.
 
    :field distanceMultipler: Specifies a factor to multiply
-                             all distances returned by
+                             all distance fields returned by
                              :dbcommand:`geoNear`. For example, use
                              ``distanceMultiplier`` to convert from
                              spherical queries returned in radians to
-                             linear units (i.e. miles or kilometers)
-                             by multiplying by the radius of the
-                             Earth.
+                             distance units.
 
-   :field box: Specifies a rectangle or box shape to query within. To
-               specify the bounds of the rectangle, you must specify
-               the bottom left and top right corners of the rectangle
-               in an array object.
-
-   .. TODO is this really 'circle'??? 
-
-   :field circle: Specifies a circular shape to query within. To
-                  specify the bounds of the circle, you must specify
-                  the center point in an array and the radius of the circle.
-
-   :field polygon: Specifies a polygon shape to query within. To
-                   specify the bounds of the polygon, you must specify
-                   an array of points. The last point will
-                   automatically be joined with the first one.
-
-   :option boolean spherical: Specifies whether to use spherical
-                              coordinate system to calculate
-                              distances.
+   :field spherical: Specifies whether to use spherical coordinate
+                     system to calculate distances.
 
    .. read-lock, slave-ok
 
@@ -1000,12 +980,12 @@ Geospatial Commands
    The :dbcommand:`geoSearch` command provides an interface to
    MongoDB's :term:`haystack index` functionality. These indexes are
    useful for returning results based on location coordinates *after*
-   collecting results based on some other query (i.e. a "haystack.")
+   collecting results based on another query (i.e. a "haystack.")
    Consider the following example:
 
    .. code-block:: javascript
 
-      { geoSearch : "places", near : [33, 33], maxDistance : 6, search : { type : "restaurant" }, limit : 30 }
+      { geoSearch: "places", near: [33, 33], search: { type: "restaurant" } }
 
    The above command returns all documents with a ``type`` of
    ``restaurant`` having a maximum distance of 6 units from the
@@ -1015,6 +995,18 @@ Geospatial Commands
    Unless specified otherwise, the :dbcommand:`geoSearch` command
    limits results to 50 documents.
 
+   The :dbcommand:`geoSearch` command provides the following options:
+
+   :field near: Takes the coordinates (e.g. ``[ x, y ]``) to use as
+                the center of a geospatial query.
+
+   :field num: Specifies the maximum number of documents to return.
+
+   :field maxDistance: Limits the results to those falling within
+                       a given distance of the center coordinate.
+
+   :field search: Specifies another field to query the haystack index.
+
    .. read-lock, slave-ok
 
 Collections
diff --git a/source/reference/operators.txt b/source/reference/operators.txt
index e6d07b1f81a..b17d2304979 100644
--- a/source/reference/operators.txt
+++ b/source/reference/operators.txt
@@ -272,22 +272,22 @@ Geospatial
 
    Replace ``{ shape }`` with a document that describes a shape. The
    :operator:`$within` operator supports three basic shape types. These
-   shapes and the relevant expressions follow:
+   shapes are:
 
    .. operator:: $box
 
-      The :operator:`$box` operator specifies a box or rectangle shape
-      for the :operator:`$within` operator. To use the
-      :operator:`$box` operator, you must specify the bottom left and
-      top right corners of the rectangle in an array object. Consider the
-      following example:
+      The :operator:`$box` operator specifies a rectangular shape for
+      the :operator:`$within` operator. To use the :operator:`$box`
+      operator, you must specify the bottom left and top right corners
+      of the rectangle in an array object. Consider the following
+      example:
 
       .. code-block:: javascript
 
          db.collection.find( { loc: { $within: { $box: [ [0,0], [100,100] ] } } } )
 
       This will return all the documents that are within the box
-      having points: [0,0], [0,100], [100,0], and [100,100].
+      having points: ``[0,0]``, ``[0,100]``, ``[100,0]``, and ``[100,100]``.
 
    .. operator:: $center
 
@@ -306,26 +306,26 @@ Geospatial
          db.collection.find( { location: { $within: { $center: [ [0,0], 10 } } } );
 
       The above command returns all the documents that fall within a
-      10 unit radius of the point [0,0].
+      10 unit radius of the point ``[0,0]``.
 
    .. operator:: $polygon
 
-      The :operator:`$polygon` operator specifies a polygon shape for
-      the :operator:`$within` operator. To define the bounds of the
-      polygon, you must specify an array of coordinate points. The
-      last point is always implicitly connected to the first
-      point. You can specify an arbitrary number of points to create
-      an multipoint polygon. See the following example:
+      Use :operator:`$polygon` to specify a polgon for a bounded query
+      using the :operator:`$within` operator. To define the polygon,
+      you must specify an array of coordinate points, as in the
+      following:
+
+          [ [ x1,y1 ], [x2,y2], [x3,y3] ]
+
+      The last point specified is always implicitly connected to the
+      first. You can specify as many points, and therfore sides, as
+      you like. Consider the following bounded query for documents
+      with coordinates within a polygon:
 
       .. code-block:: javascript
 
          db.collection.find( { loc: { $within: { $polygon: [ [0,0], [3,6], [6,0]  ] } } } )
 
-      This will return all the documents that are within the polygon
-      [0,0], [3,6], [6,0]. This is useful for searching within
-      specific areas that correspond to irregularly shaped areas such
-      as a dense urban neighborhood.
-
    All shapes include the border of the shape as part of the shape,
    although this is subject to the imprecision of floating point
    calculations.
@@ -333,21 +333,25 @@ Geospatial
 .. operator:: $nearSphere
 
    The :operator:`$nearSphere` operator returns all documents near a
-   point using spherical representation system to calculate distances.
+   point calculating distances based on a :ref:`spherical
+   representation system <geospatial-query-spherical>`.
 
    .. code-block:: javascript
 
       db.collection.find( { loc: { $nearSphere: [0,0] } } )
 
-   This will return all documents near [0,0] using a spherical
-   representation system to calculate distances from [0,0].
-
 .. operator:: $centerSphere
 
-   The :operator:`$centerSphere` operator returns all the documents that
-   are within a certain radius from a point using spherical
-   representation. To define the bounds of the :operator:`$centerSphere` operator,
-   you must specify the center point and the radius.
+   .. TODO rework the opening. 
+
+   The :operator:`$centerSphere` operator specifies a 
+   within a certain radius from a point calculating distances based on
+   :ref:`spherical representation system
+   <geospatial-query-spherical>`.
+
+   To define the
+   bounds of the circle, you must specify the center point and the
+   radius.
 
    Considering the following example:
 
@@ -355,14 +359,9 @@ Geospatial
 
       db.collection.find( { loc: { $centerSphere: { [0,0], 10 / 3959 } } } )
 
-   This will return all documents with a coordinate pair that is
-   within a 10 mile radius of [0,0] using a spherical representation
-   system to calculate distances from [0,0].
-
-   .. note::
-
-      For spherical queries, you must convert distances to radians for
-      proper results.
+   This query returns all documents that have a coordinate pair in the
+   ``loc`` field that is within a 10 mile radius of ``[0,0]`` using a
+   spherical representation system to calculate distances.
 
 .. operator:: $uniqueDocs
 
@@ -370,15 +369,13 @@ Geospatial
    behavior when :ref:`multiple location documents
    <geospatial-query-multi-location>` are used.
 
-   .. TODO check this functionality again.
-
    When querying multiple location documents using the
    :operator:`$within` operator, MongoDB will return matching documents
    once, even if there are multiple matches in the location fields.
 
    By specifying ``$uniqueDocs: false`` in the :operator:`$within`
    operator, matching documents may be returned multiple times if
-   there are multiple matches.
+   there are multiple matches in the location field.
 
    .. code-block:: javascript
 
@@ -390,7 +387,8 @@ Geospatial
 
    If you specify ``uniqueDocs: true`` as an option to the
    :dbcommand:`geoNear` command, then MongoDB will only return a
-   single document, even if there are multiple matches.
+   single document, even if there are multiple matches in the location
+   field, as in the following operation:
 
    .. code-block:: javascript
 
@@ -399,10 +397,8 @@ Geospatial
    .. note::
 
       You cannot specify :operator:`$uniqueDocs` with
-      :operator:`$near` or haystack queries.
-
-
-
+      :operator:`$near` or :dbcommand:`geoSearch` for :ref:`haystack
+      indexes <geospatial-haystack-index>`.
 
 .. index:: query selectors; logical
 .. _query-selectors-logical:

From 7d4e03f3093b4515c2f11ea6b07b286ff4d42803 Mon Sep 17 00:00:00 2001
From: Andrew Leung <andrew.leung@10gen.com>
Date: Wed, 1 Aug 2012 14:54:32 -0400
Subject: [PATCH 11/16] fixing up geoSearch example. DOCS-151

---
 source/reference/commands.txt | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/source/reference/commands.txt b/source/reference/commands.txt
index 9cd685d8e83..7b467921697 100644
--- a/source/reference/commands.txt
+++ b/source/reference/commands.txt
@@ -988,9 +988,8 @@ Geospatial Commands
       { geoSearch: "places", near: [33, 33], search: { type: "restaurant" } }
 
    The above command returns all documents with a ``type`` of
-   ``restaurant`` having a maximum distance of 6 units from the
-   coordinates ``[30,33]`` in the collection ``places`` up to a
-   maximum of 30 results.
+   ``restaurant`` near the coordinates ``[30,33]`` in the collection
+   ``places``.
 
    Unless specified otherwise, the :dbcommand:`geoSearch` command
    limits results to 50 documents.

From 80661ecef257640f937f351a71983999a5809be1 Mon Sep 17 00:00:00 2001
From: Andrew Leung <andrew.leung@10gen.com>
Date: Wed, 1 Aug 2012 16:46:23 -0400
Subject: [PATCH 12/16] fixing up  and

---
 source/reference/operators.txt | 18 +++++++-----------
 1 file changed, 7 insertions(+), 11 deletions(-)

diff --git a/source/reference/operators.txt b/source/reference/operators.txt
index b17d2304979..95907227733 100644
--- a/source/reference/operators.txt
+++ b/source/reference/operators.txt
@@ -332,9 +332,10 @@ Geospatial
 
 .. operator:: $nearSphere
 
-   The :operator:`$nearSphere` operator returns all documents near a
-   point calculating distances based on a :ref:`spherical
-   representation system <geospatial-query-spherical>`.
+   Similar to the :operator:`$near`, the :operator:`$nearSphere`
+   operator returns all documents near a point calculating distances
+   based on a :ref:`spherical representation system
+   <geospatial-query-spherical>`.
 
    .. code-block:: javascript
 
@@ -342,17 +343,12 @@ Geospatial
 
 .. operator:: $centerSphere
 
-   .. TODO rework the opening. 
-
-   The :operator:`$centerSphere` operator specifies a 
-   within a certain radius from a point calculating distances based on
+   Similar to the :operator:`$center` operator,
+   :operator:`$centerSphere` returns all documents in a circle
+   specified by a point and radius and calculating distances based on
    :ref:`spherical representation system
    <geospatial-query-spherical>`.
 
-   To define the
-   bounds of the circle, you must specify the center point and the
-   radius.
-
    Considering the following example:
 
    .. code-block:: javascript

From d35e3b659717f43a23d12e4e4cb5580f086547fd Mon Sep 17 00:00:00 2001
From: Andrew Leung <andrew.leung@10gen.com>
Date: Wed, 1 Aug 2012 16:51:34 -0400
Subject: [PATCH 13/16] resetting draft geo doc DOCS-151

---
 draft/applications/geospatial-indexes.txt | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/draft/applications/geospatial-indexes.txt b/draft/applications/geospatial-indexes.txt
index 20e93662a87..6057aa77958 100644
--- a/draft/applications/geospatial-indexes.txt
+++ b/draft/applications/geospatial-indexes.txt
@@ -208,8 +208,8 @@ Circles
 
 To return results within the :ref:`bounds <geospatial-query-bounded>`
 of a circle, you must specify the center and the radius of the circle,
-using the :operator:`$within` operator and the :operator:`$center`
-operator. Consider the following prototype query:
+using the :operator:`$within` operator and the :operator:`$circle`
+option. Consider the following prototype query:
 
 .. code-block:: javascript
 
@@ -364,8 +364,6 @@ their distance from the ``[ -74, 40.74 ]`` point.
 
 .. TODO add in distanceMultiplier description
 
-.. _geospatial-query-multi-location:
-
 Multi-location Documents
 ------------------------
 
@@ -431,6 +429,4 @@ in the following example:
 
    db.records.ensureIndex( { "addresses.loc": "2d" } )
 
-.. TODO include: includeLocs field
-
 .. includes:: /includes/geospatial-sharding.rst

From 6c54340576023054691978c9ebc2fe372d568744 Mon Sep 17 00:00:00 2001
From: Andrew Leung <andrew.leung@10gen.com>
Date: Wed, 1 Aug 2012 18:51:07 -0400
Subject: [PATCH 14/16] adding in includeLocs for commands - DOCS-151

---
 draft/applications/geospatial-indexes.txt | 8 ++++++--
 source/reference/commands.txt             | 9 +++++++++
 2 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/draft/applications/geospatial-indexes.txt b/draft/applications/geospatial-indexes.txt
index 6057aa77958..20e93662a87 100644
--- a/draft/applications/geospatial-indexes.txt
+++ b/draft/applications/geospatial-indexes.txt
@@ -208,8 +208,8 @@ Circles
 
 To return results within the :ref:`bounds <geospatial-query-bounded>`
 of a circle, you must specify the center and the radius of the circle,
-using the :operator:`$within` operator and the :operator:`$circle`
-option. Consider the following prototype query:
+using the :operator:`$within` operator and the :operator:`$center`
+operator. Consider the following prototype query:
 
 .. code-block:: javascript
 
@@ -364,6 +364,8 @@ their distance from the ``[ -74, 40.74 ]`` point.
 
 .. TODO add in distanceMultiplier description
 
+.. _geospatial-query-multi-location:
+
 Multi-location Documents
 ------------------------
 
@@ -429,4 +431,6 @@ in the following example:
 
    db.records.ensureIndex( { "addresses.loc": "2d" } )
 
+.. TODO include: includeLocs field
+
 .. includes:: /includes/geospatial-sharding.rst
diff --git a/source/reference/commands.txt b/source/reference/commands.txt
index 7b467921697..87c833cbe7c 100644
--- a/source/reference/commands.txt
+++ b/source/reference/commands.txt
@@ -973,6 +973,15 @@ Geospatial Commands
    :field spherical: Specifies whether to use spherical coordinate
                      system to calculate distances.
 
+   .. This is a version 2.0 item
+
+   .. versionadded:: 2.0
+
+   :field includeLocs: A boolean variable to include the location
+                       field with the distance field when using
+                       :ref:`Multi-location documents
+                       <geospatial-multi-location>`.
+
    .. read-lock, slave-ok
 
 .. dbcommand:: geoSearch

From 6fab9e2f64d23692bf3df41976f74d5d2cec0b18 Mon Sep 17 00:00:00 2001
From: Andrew Leung <andrew.leung@10gen.com>
Date: Thu, 2 Aug 2012 15:22:35 -0400
Subject: [PATCH 15/16] fixing up geoNear entries and tightening nearSphere and
 centerSphere

---
 draft/applications/geospatial-indexes.txt |  6 -----
 source/reference/commands.txt             | 10 +++++++--
 source/reference/operators.txt            | 27 ++++++-----------------
 3 files changed, 15 insertions(+), 28 deletions(-)

diff --git a/draft/applications/geospatial-indexes.txt b/draft/applications/geospatial-indexes.txt
index 20e93662a87..63d7619e413 100644
--- a/draft/applications/geospatial-indexes.txt
+++ b/draft/applications/geospatial-indexes.txt
@@ -362,10 +362,6 @@ their distance from the ``[ -74, 40.74 ]`` point.
    between ``-180`` inclusive, and ``180``, valid values for latitude
    are between ``-90`` and ``90``.
 
-.. TODO add in distanceMultiplier description
-
-.. _geospatial-query-multi-location:
-
 Multi-location Documents
 ------------------------
 
@@ -431,6 +427,4 @@ in the following example:
 
    db.records.ensureIndex( { "addresses.loc": "2d" } )
 
-.. TODO include: includeLocs field
-
 .. includes:: /includes/geospatial-sharding.rst
diff --git a/source/reference/commands.txt b/source/reference/commands.txt
index 87c833cbe7c..b076eef7541 100644
--- a/source/reference/commands.txt
+++ b/source/reference/commands.txt
@@ -970,8 +970,14 @@ Geospatial Commands
                              spherical queries returned in radians to
                              distance units.
 
-   :field spherical: Specifies whether to use spherical coordinate
-                     system to calculate distances.
+   :field spherical: If set to ``true``, spherical coordinate system
+                     will be used to calculate distances between
+                     points.
+
+   :field uniqueDocs: If set to ``true``, a document will only appear
+                      once in the results, even if there are multiple
+                      matches multiple location fields of the document.
+
 
    .. This is a version 2.0 item
 
diff --git a/source/reference/operators.txt b/source/reference/operators.txt
index 95907227733..f0cdbd9803d 100644
--- a/source/reference/operators.txt
+++ b/source/reference/operators.txt
@@ -332,8 +332,9 @@ Geospatial
 
 .. operator:: $nearSphere
 
-   Similar to the :operator:`$near`, the :operator:`$nearSphere`
-   operator returns all documents near a point calculating distances
+   The :operator:`$nearSphere` operator is the spherical equivalent of
+   the :operator:`$near` operator. The :operator:`$nearSphere`
+   operator returns all documents near a point, calculating distances
    based on a :ref:`spherical representation system
    <geospatial-query-spherical>`.
 
@@ -343,11 +344,10 @@ Geospatial
 
 .. operator:: $centerSphere
 
-   Similar to the :operator:`$center` operator,
-   :operator:`$centerSphere` returns all documents in a circle
-   specified by a point and radius and calculating distances based on
-   :ref:`spherical representation system
-   <geospatial-query-spherical>`.
+   The :operator:`$centerSphere` operator is the spherical equivalent
+   of the :operator:`$center` operator. The :operator:`$centerSphere`
+   operator uses a spherical system to calculate distances in a circle
+   specified by a point and radius.
 
    Considering the following example:
 
@@ -377,19 +377,6 @@ Geospatial
 
       db.places.find( { loc : { $within : { $center : [[0.5, 0.5], 20], $uniqueDocs : true } } } )
       
-   When using the :dbcommand:`geoNear` command, if a document contains
-   more than one field with coordinate values, MongoDB will return the
-   same document multiple times.
-
-   If you specify ``uniqueDocs: true`` as an option to the
-   :dbcommand:`geoNear` command, then MongoDB will only return a
-   single document, even if there are multiple matches in the location
-   field, as in the following operation:
-
-   .. code-block:: javascript
-
-      db.runCommand( { geoNear : "collection" , near : [0,0], num : 10, uniqueDocs : false } )
-
    .. note::
 
       You cannot specify :operator:`$uniqueDocs` with

From 768e70a225a3a8145f48dd8ed9cddba1434a6d93 Mon Sep 17 00:00:00 2001
From: Andrew Leung <andrew.leung@10gen.com>
Date: Fri, 3 Aug 2012 13:11:32 -0400
Subject: [PATCH 16/16] temp update of geoOperators.

---
 source/reference/commands.txt  | 54 ++++++++++++++++++----------------
 source/reference/glossary.txt  |  4 +--
 source/reference/operators.txt | 21 +++++++------
 3 files changed, 41 insertions(+), 38 deletions(-)

diff --git a/source/reference/commands.txt b/source/reference/commands.txt
index b076eef7541..efad3d5a7ed 100644
--- a/source/reference/commands.txt
+++ b/source/reference/commands.txt
@@ -934,6 +934,8 @@ Replication
 Geospatial Commands
 ~~~~~~~~~~~~~~~~~~~
 
+.. TODO read section outloud to self
+
 .. dbcommand:: geoNear
 
    The :dbcommand:`geoNear` command provides an alternative to the
@@ -950,18 +952,18 @@ Geospatial Commands
 
    The :dbcommand:`geoNear` command provides the following options:
 
-   :field near: Takes the coordinates (e.g. ``[ x, y ]``) to use as
-                the center of a geospatial query.
+   :field coordinate near: Takes the coordinates (e.g. ``[ x, y ]``) to use as
+                           the center of a geospatial query.
 
    :field num: Specifies the maximum number of documents to return.
 
-   :field maxDistance: Limits the results to those falling within
-                       a given distance of the center coordinate.
+   :field maxDistance: Limits the results to those within a given
+                       distance of the center coordinate.
 
    :field query: Further narrows the results using any standard
-                 MongoDB query operator or selection. See :func:`db.collection.find()`
-                 and ":doc:`/reference/operators`" for more
-                 information.
+                 MongoDB query operator or selection. See
+                 :func:`db.collection.find()` and
+                 ":doc:`/reference/operators`" for more information.
 
    :field distanceMultipler: Specifies a factor to multiply
                              all distance fields returned by
@@ -969,24 +971,26 @@ Geospatial Commands
                              ``distanceMultiplier`` to convert from
                              spherical queries returned in radians to
                              distance units.
-
-   :field spherical: If set to ``true``, spherical coordinate system
-                     will be used to calculate distances between
-                     points.
-
-   :field uniqueDocs: If set to ``true``, a document will only appear
-                      once in the results, even if there are multiple
-                      matches multiple location fields of the document.
-
-
-   .. This is a version 2.0 item
-
-   .. versionadded:: 2.0
-
-   :field includeLocs: A boolean variable to include the location
-                       field with the distance field when using
-                       :ref:`Multi-location documents
-                       <geospatial-multi-location>`.
+			     .. TODO redo above... 
+
+   :field boolean spherical: If set to ``true``, MongoDB will use
+                             spherical geometry to calculate
+                             distances. The default is ``false``,
+                             MongoDB uses plane geometry to calculate
+                             distances.
+
+   :field boolean uniqueDocs: If set to ``true``, a document will only
+                              appear once in the result set, even if a
+                              query matches :ref:`multiple location
+                              fields <geospatial-query-multiple>` of
+                              the document. The default is ``false``,
+                              where a document may appear multiple
+                              times in the result set.
+
+   :field boolean includeLocs: A boolean variable to include the
+                               location field with the distance field
+                               when using :ref:`Multi-location
+                               documents <geospatial-multi-location>`.
 
    .. read-lock, slave-ok
 
diff --git a/source/reference/glossary.txt b/source/reference/glossary.txt
index 463bcd98607..0cb59b11639 100644
--- a/source/reference/glossary.txt
+++ b/source/reference/glossary.txt
@@ -812,5 +812,5 @@ Glossary
       ObjectId values as the default values for :term:`_id` fields.
 
    Geohash
-      A value is a binary representation of the location on a
-      coordinate grid.
+      A value that is a binary representation of a location on a
+      coordinate grid. Used in MongoDB's geospatial index system.
diff --git a/source/reference/operators.txt b/source/reference/operators.txt
index f0cdbd9803d..c48415ebb12 100644
--- a/source/reference/operators.txt
+++ b/source/reference/operators.txt
@@ -333,10 +333,8 @@ Geospatial
 .. operator:: $nearSphere
 
    The :operator:`$nearSphere` operator is the spherical equivalent of
-   the :operator:`$near` operator. The :operator:`$nearSphere`
-   operator returns all documents near a point, calculating distances
-   based on a :ref:`spherical representation system
-   <geospatial-query-spherical>`.
+   the :operator:`$near` operator. :operator:`$nearSphere` returns all
+   documents near a point, calculating distances using spherical geometry.
 
    .. code-block:: javascript
 
@@ -345,9 +343,9 @@ Geospatial
 .. operator:: $centerSphere
 
    The :operator:`$centerSphere` operator is the spherical equivalent
-   of the :operator:`$center` operator. The :operator:`$centerSphere`
-   operator uses a spherical system to calculate distances in a circle
-   specified by a point and radius.
+   of the :operator:`$center` operator. :operator:`$centerSphere` uses
+   spherical geometry to calculate distances in a circle specified by
+   a point and radius.
 
    Considering the following example:
 
@@ -355,12 +353,13 @@ Geospatial
 
       db.collection.find( { loc: { $centerSphere: { [0,0], 10 / 3959 } } } )
 
-   This query returns all documents that have a coordinate pair in the
-   ``loc`` field that is within a 10 mile radius of ``[0,0]`` using a
-   spherical representation system to calculate distances.
+   This query will return all documents within a 10 mile radius of
+   ``[0,0]`` using a spherical geometry to calculate distances.
 
 .. operator:: $uniqueDocs
 
+   .. TODO read aloud
+
    The :operator:`$uniqueDocs` operator overrides default query
    behavior when :ref:`multiple location documents
    <geospatial-query-multi-location>` are used.
@@ -376,7 +375,7 @@ Geospatial
    .. code-block:: javascript
 
       db.places.find( { loc : { $within : { $center : [[0.5, 0.5], 20], $uniqueDocs : true } } } )
-      
+
    .. note::
 
       You cannot specify :operator:`$uniqueDocs` with