In ctor of GeoPointFieldMapper, geohash_prefix now implicitly enables geohash option

Also improved docs for geopoint type and geohash_cell filte

Closes #3951

docs/reference/api-conventions.asciidoc

@@ -78,6 +78,28 @@ fields within a document indexed treated as boolean fields.
 All REST APIs support providing numbered parameters as `string` on top
 of supporting the native JSON number types.
 
+[[distance-units]]
+[float]
+=== Distance Units
+
+Wherever distances need to be specified, such as the `distance` parameter in
+the <<query-dsl-geo-distance-filter>>) or the `precision` parameter in the
+<<query-dsl-geohash-cell-filter>>, the default unit if none is specified is
+the meter. Distances can be specified in other units, such as `"1km"` or
+`"2mi"` (2 miles).
+
+The full list of units is listed below:
+
+[horizontal]
+Mile::          `mi` or `miles`
+Yard::          `yd` or `yards`
+Inch::          `in` or `inch`
+Kilometer::     `km` or `kilometers`
+Meter::         `m` or `meters`
+Centimeter::    `cm` or `centimeters`
+Millimeter::    `mm` or `millimeters`
+
+
 [float]
 === Result Casing
 

docs/reference/mapping/types/geo-point-type.asciidoc

@@ -32,6 +32,29 @@ depends on the data set which one performs better. Note though, that
 indexed lat lon only make sense when there is a single geo point value
 for the field, and not multi values.
 
+[float]
+==== Geohashes
+
+Geohashes are a form of lat/lon encoding which divides the earth up into
+a grid. Each cell in this grid is represented by a geohash string. Each
+cell in turn can be further subdivided into smaller cells which are
+represented by a longer string. So the longer the geohash, the smaller
+(and thus more accurate) the cell is.
+
+Because geohashes are just strings, they can be stored in an inverted
+index like any other string, which makes querying them very efficient.
+
+If you enable the `geohash` option, a `geohash` ``sub-field'' will be
+indexed as, eg `pin.geohash`. The length of the geohash is controlled by
+the `geohash_precision` parameter, which can either be set to an absolute
+length (eg `12`, the default) or to a distance (eg `1km`).
+
+More usefully, set the `geohash_prefix` option to `true` to not only index
+the geohash value, but all the enclosing cells as well.  For instance, a
+geohash of `u30` will be indexed as `[u,u3,u30]`. This option can be used
+by the <<query-dsl-geohash-cell-filter>> to find geopoints within a
+particular cell very efficiently.
+
 [float]
 ==== Input Structure
 
@@ -106,7 +129,14 @@ Defaults to `false`.
 |`geohash` |Set to `true` to also index the `.geohash` as a field.
 Defaults to `false`.
 
-|`geohash_precision` |Sets the geohash precision, defaults to 12.
+|`geohash_precision` |Sets the geohash precision. It can be set to an
+absolute geohash length or a distance value (eg 1km, 1m, 1ml) defining
+the size of the smallest cell. Defaults to an absolute length of 12.
+
+|`geohash_prefix` |If this option is set to `true`, not only the geohash
+but also all its parent cells (true prefixes) will be indexed as well. The
+number of terms that will be indexed depends on the `geohash_precision`.
+Defaults to `false`. *Note*: This option implicitly enables `geohash`.
 
 |`validate` |Set to `true` to reject geo points with invalid latitude or
 longitude (default is `false`) *Note*: Validation only works when

docs/reference/query-dsl/filters/geo-distance-filter.asciidoc

@@ -36,7 +36,7 @@ filter:
             }
         }
     }
-}    
+}
 --------------------------------------------------
 
 [float]
@@ -138,23 +138,27 @@ Format in `lat,lon`.
 
 The following are options allowed on the filter:
 
-[cols="<,<",options="header",]
-|=======================================================================
-|Option |Description
-|`distance` |The distance to include hits in the filter. The distance
-can be a numeric value, and then the `unit` (either `mi`, `miles`, `in`, `inch`, `yd`, `yards`, `km`, `kilometers`,
-`mm`, `millimeters`, `cm`, `centimeters`, `m` or `meters` can be set) controlling the unit.
-Or a single string with the unit as well.
-
-|`distance_type` |How to compute the distance. Can either be `arc`
-(better precision) or `plane` (faster). Defaults to `arc`.
-
-|`optimize_bbox` |Will an optimization of using first a bounding box
-check will be used. Defaults to `memory` which will do in memory checks.
-Can also have values of `indexed` to use indexed value check (make sure
-the `geo_point` type index lat lon in this case), or `none` which
-disables bounding box optimization.
-|=======================================================================
+[horizontal]
+
+`distance`::
+
+    The radius of the circle centred on the specified location. Points which
+    fall into this circle are considered to be matches. The `distance` can be
+    specified in various units. See <<distance-units>>.
+
+`distance_type`::
+
+    How to compute the distance. Can either be `arc` (better precision) or
+    `plane` (faster). Defaults to `arc`.
+
+`optimize_bbox`::
+
+    Whether to use the optimization of first running a bounding box check
+    before the distance check. Defaults to `memory` which will do in memory
+    checks. Can also have values of `indexed` to use indexed value check (make
+    sure the `geo_point` type index lat lon in this case), or `none` which
+    disables bounding box optimization.
+
 
 [float]
 ==== geo_point Type

docs/reference/query-dsl/filters/geohash-cell-filter.asciidoc

@@ -1,18 +1,15 @@
 [[query-dsl-geohash-cell-filter]]
 === Geohash Cell Filter
 
-A geohash is a hierarchical datastructure which allows a division of a
-spatial geometry. Each geohash defines a cell on the earths surface and
-the longer the geohash the smaller cell. Also the size of a cell can be
-seen as precision. The geohash filter provides an access to this
-datastructure by defining a cell and match only points that lie within
-this cell.
+The `geohash_cell` filter provides access to a hierarchy of geohashes.
+By defining a geohash cell, only <<mapping-geo-point-type,geopoints>>
+within this cell will match this filter.
 
 To get this filter work all prefixes of a geohash need to be indexed. In
 example a geohash `u30` needs to be decomposed into three terms: `u30`,
 `u3` and `u`. This decomposition must be enabled in the mapping of the
-`geo_point` field that's going to be filtered by setting the
-`geohash_prefix` option:
+<<mapping-geo-point-type,geopoint>> field that's going to be filtered by
+setting the `geohash_prefix` option:
 
 [source,js]
 --------------------------------------------------
@@ -23,7 +20,8 @@ example a geohash `u30` needs to be decomposed into three terms: `u30`,
                 "pin": {
                     "type": "geo_point",
                     "geohash": true,
-                    "geohash_prefix": true
+                    "geohash_prefix": true,
+                    "geohash_precision": 10
                 }
             }
         }
@@ -31,14 +29,16 @@ example a geohash `u30` needs to be decomposed into three terms: `u30`,
 }
 --------------------------------------------------
 
-The geohash cell can defined by all formats of `geo_points`. If such a
-cell is defined by a latitude and longitude pair the size of the cell
-needs to be setup. This can be done by the `precision` parameter of the
-filter. This parameter can be set to an integer value which sets the
-length of the geohash prefix. Instead of setting a geohash length
-directly it is also possible to define the precision as distance, in
-example `"precision": "50m"`. The `neighbor` option of the filter offers
-the possibility to filter cells next to the given cell.
+The geohash cell can defined by all formats of `geo_points`. If such a cell is
+defined by a latitude and longitude pair the size of the cell needs to be
+setup. This can be done by the `precision` parameter of the filter. This
+parameter can be set to an integer value which sets the length of the geohash
+prefix. Instead of setting a geohash length directly it is also possible to
+define the precision as distance, in example `"precision": "50m"`. (See
+<<distance-units>>.)
+
+The `neighbor` option of the filter offers the possibility to filter cells
+next to the given cell.
 
 [source,js]
 --------------------------------------------------

src/main/java/org/elasticsearch/index/mapper/geo/GeoPointFieldMapper.java

@@ -214,6 +214,7 @@ public class GeoPointFieldMapper implements Mapper, ArrayValueMapperParser {
                     builder.geohashPrefix(XContentMapValues.nodeBooleanValue(fieldNode));
                     if (XContentMapValues.nodeBooleanValue(fieldNode)) {
                         // automatically set geohash to true as well...
+                        // TODO: Should we do this in the builder
                         builder.enableGeoHash(true);
                     }
                 } else if (fieldName.equals("precision_step")) {
@@ -275,7 +276,7 @@ public class GeoPointFieldMapper implements Mapper, ArrayValueMapperParser {
         this.name = name;
         this.pathType = pathType;
         this.enableLatLon = enableLatLon;
-        this.enableGeoHash = enableGeoHash;
+        this.enableGeoHash = enableGeoHash || enableGeohashPrefix; // implicitly enable geohashes if geohash_prefix is set
         this.enableGeohashPrefix = enableGeohashPrefix;
         this.precisionStep = precisionStep;
         this.precision = precision;