From aee9e5bc7ee03cb881fabcdcd2b6699bcda4ac9f Mon Sep 17 00:00:00 2001
From: schmalliso <allison.moore@10gen.com>
Date: Thu, 20 Jun 2013 12:32:32 -0400
Subject: [PATCH] DOCS-1551 & 1552 clarifying how GeoJSON polygons work in
 Mongo & adding example

---
 source/core/2dsphere.txt                | 36 +++++++++++++++++++++----
 source/reference/glossary.txt           | 23 ++++++++++++++++
 source/reference/operator/geoWithin.txt | 12 ++++-----
 3 files changed, 60 insertions(+), 11 deletions(-)

diff --git a/source/core/2dsphere.txt b/source/core/2dsphere.txt
index 0c01e1d7cb5..3622f148c45 100644
--- a/source/core/2dsphere.txt
+++ b/source/core/2dsphere.txt
@@ -40,11 +40,11 @@ Store GeoJSON Objects
 
 MongoDB supports the following GeoJSON objects:
 
-  - Point
+  - :term:`Point`
 
-  - LineString
+  - :term:`LineString`
 
-  - Polygon
+  - :term:`Polygon`
 
 In order to index GeoJSON data, you must store the data in a location
 field that you name. The location field contains a subdocument with a
@@ -76,8 +76,14 @@ The following example stores a GeoJSON ``LineString``:
              coordinates : [ [ 40 , 5 ] , [ 41 , 6 ] ]
    } }
 
-The following example stores a GeoJSON ``Polygon`` with an exterior ring
-and no interior rings (or holes):
+:term:`Polygons <Polygon>` consist of an array of GeoJSON
+``LinearRing`` coordinate arrays. These ``LinearRings`` are closed
+LineStrings (i.e. their first and last coordinates are the same
+position), with at least four coordinate pairs.
+
+The following example stores a GeoJSON ``Polygon`` with an exterior
+ring and no interior rings (or holes). Note the first and last
+coordinate pair with the ``[ 0 , 0 ]`` coordinate:
 
 .. code-block:: javascript
 
@@ -86,6 +92,26 @@ and no interior rings (or holes):
         coordinates : [ [ [ 0 , 0 ] , [ 3 , 6 ] , [ 6 , 1 ] , [ 0 , 0 ] ] ]
    } }
 
+For Polygons with multiple rings, 
+
+- the first described ring must be the exterior ring
+- the exterior ring cannot self-intersect
+- any interior ring must be entirely contained by the outer ring
+- interior rings cannot intersect or overlap each each other (but can
+  share an edge)
+
+The following example stores a GeoJSON ``Polygon`` with an interior
+ring:
+
+.. code-block:: javascript
+
+   { loc :
+      { type : "Polygon" ,
+        coordinates : [ [ [ 0 , 0 ] , [ 3 , 6 ] , [ 6 , 1 ] , [ 0 , 0 ] ],
+                        [ [ 2 , 2 ] , [ 3 , 3 ] , [ 4 , 2 ] , [ 2 , 2 ] ] ]
+   } }
+
+
 .. _geospatial-indexes-create-2dsphere:
 
 Create a ``2dsphere`` Index
diff --git a/source/reference/glossary.txt b/source/reference/glossary.txt
index b659fbe8a47..6c22f74d18d 100644
--- a/source/reference/glossary.txt
+++ b/source/reference/glossary.txt
@@ -925,3 +925,26 @@ Glossary
       an Earth-like sphere. MongoDB uses the WGS84 datum for geospatial
       queries on :term:`GeoJSON` objects. See
       `http://spatialreference.org/ref/epsg/4326/ <http://spatialreference.org/ref/epsg/4326/>`_.
+
+   Point
+      A point is a single coordinate pair, or "position," as described in `the
+      GeoJSON specification
+      <http://geojson.org/geojson-spec.html#point>`_.
+      
+   LineString 
+      A LineString is defined by an array of two
+      or more positions. A closed LineString with four or more
+      positions is called a LinearRing, as described in `the
+      GeoJSON specification
+      <http://geojson.org/geojson-spec.html#linestring>`_.
+      
+   Polygon 
+      A Polygon is defined by an array of :term:`LinearRing
+      <LineString>` coordinate arrays, as described in `the GeoJSON
+      specification <http://geojson.org/geojson-spec.html#polygon>`_.
+      For Polygons with multiple rings, the first **must** be the
+      exterior ring and any others must be interior rings or holes.
+      
+      MongoDB does not permit the exterior ring to self-intersect, and
+      interior rings must be fully contained within the outer loop and
+      cannot intersect or overlap with each other.
diff --git a/source/reference/operator/geoWithin.txt b/source/reference/operator/geoWithin.txt
index dbc6761cb31..7b370acd522 100644
--- a/source/reference/operator/geoWithin.txt
+++ b/source/reference/operator/geoWithin.txt
@@ -33,12 +33,12 @@ $geoWithin
       index. However, a geospatial index will improve query
       performance.
 
-   If querying for inclusion in a GeoJSON polygon on a sphere, pass the
-   polygon to :operator:`$geoWithin` through the :operator:`$geometry`
-   operator. Coordinates of a polygon are an array of LinearRing
-   coordinate arrays. The first element in the array represents the
-   exterior ring. Any subsequent elements represent interior rings (or
-   holes).
+   If querying for inclusion in a GeoJSON :term:`polygon <Polygon>` on
+   a sphere, pass the polygon to :operator:`$geoWithin` through the
+   :operator:`$geometry` operator. The coordinates of a polygon are an
+   array of LinearRing coordinate arrays. The first element in the
+   array represents the exterior ring, and any subsequent elements
+   represent interior rings (or holes).
 
    For a polygon with only an exterior ring use following syntax: