Docs: java add static imports for query and filter builders

Also move and add inline comments to references

Closes #6920.

docs/java-api/query-dsl-filters.asciidoc

@@ -9,11 +9,12 @@ Once your query is ready, you can use the <<search,Search API>>.
 
 See also how to build <<query-dsl-queries,Queries>>.
 
-To use `FilterBuilders` just import them in your class:
+To use `QueryBuilders` or `FilterBuilders` just import them in your class:
 
 [source,java]
 --------------------------------------------------
-import org.elasticsearch.index.query.FilterBuilders.*;
+import static org.elasticsearch.index.query.QueryBuilders.*;
+import static org.elasticsearch.index.query.FilterBuilders.*;
 --------------------------------------------------
 
 Note that you can easily print (aka debug) JSON generated queries using
@@ -25,14 +26,13 @@ Note that you can easily print (aka debug) JSON generated queries using
 
 See {ref}/query-dsl-and-filter.html[And Filter]
 
-
 [source,java]
 --------------------------------------------------
-FilterBuilders.andFilter(
-    FilterBuilders.rangeFilter("postDate").from("2010-03-01").to("2010-04-01"),
-    FilterBuilders.prefixFilter("name.second", "ba")
-    );
+FilterBuilder filter = andFilter(
+    rangeFilter("postDate").from("2010-03-01").to("2010-04-01"),    <1>
+    prefixFilter("name.second", "ba"));                             <1>
 --------------------------------------------------
+<1> filters
 
 Note that you can cache the result using
 `AndFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>.
@@ -43,15 +43,17 @@ Note that you can cache the result using
 
 See {ref}/query-dsl-bool-filter.html[Bool Filter]
 
-
 [source,java]
 --------------------------------------------------
-FilterBuilders.boolFilter()
-    .must(FilterBuilders.termFilter("tag", "wow"))
-    .mustNot(FilterBuilders.rangeFilter("age").from("10").to("20"))
-    .should(FilterBuilders.termFilter("tag", "sometag"))
-    .should(FilterBuilders.termFilter("tag", "sometagtag"));
+FilterBuilder filter = boolFilter()
+    .must(termFilter("tag", "wow"))                     <1>
+    .mustNot(rangeFilter("age").from("10").to("20"))    <2>
+    .should(termFilter("tag", "sometag"))               <3>
+    .should(termFilter("tag", "sometagtag"));           <3>
 --------------------------------------------------
+<1> must filter
+<2> must not filter
+<3> should filter
 
 Note that you can cache the result using
 `BoolFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>.
@@ -62,11 +64,11 @@ Note that you can cache the result using
 
 See {ref}/query-dsl-exists-filter.html[Exists Filter].
 
-
 [source,java]
 --------------------------------------------------
-FilterBuilders.existsFilter("user");
+FilterBuilder filter = existsFilter("user");    <1>
 --------------------------------------------------
+<1> field
 
 
 [[ids-filter]]
@@ -74,14 +76,15 @@ FilterBuilders.existsFilter("user");
 
 See {ref}/query-dsl-ids-filter.html[IDs Filter]
 
-
 [source,java]
 --------------------------------------------------
-FilterBuilders.idsFilter("my_type", "type2").addIds("1", "4", "100");
+FilterBuilder filter = idsFilter("my_type", "type2")
+    .addIds("1", "4", "100");
 
-// Type is optional
-FilterBuilders.idsFilter().addIds("1", "4", "100");
+FilterBuilder filter = idsFilter() <1>
+    .addIds("1", "4", "100");
 --------------------------------------------------
+<1> type is optional
 
 
 [[limit-filter]]
@@ -89,11 +92,11 @@ FilterBuilders.idsFilter().addIds("1", "4", "100");
 
 See {ref}/query-dsl-limit-filter.html[Limit Filter]
 
-
 [source,java]
 --------------------------------------------------
-FilterBuilders.limitFilter(100);
+FilterBuilder filter = limitFilter(100);    <1>
 --------------------------------------------------
+<1> number of documents per shard
 
 
 [[type-filter]]
@@ -101,11 +104,11 @@ FilterBuilders.limitFilter(100);
 
 See {ref}/query-dsl-type-filter.html[Type Filter]
 
-
 [source,java]
 --------------------------------------------------
-FilterBuilders.typeFilter("my_type");
+FilterBuilder filter = typeFilter("my_type");   <1>
 --------------------------------------------------
+<1> type
 
 
 [[geo-bbox-filter]]
@@ -116,10 +119,13 @@ Bounding Box Filter]
 
 [source,java]
 --------------------------------------------------
-FilterBuilders.geoBoundingBoxFilter("pin.location")
-    .topLeft(40.73, -74.1)
-    .bottomRight(40.717, -73.99);
+FilterBuilder filter = geoBoundingBoxFilter("pin.location") <1>
+    .topLeft(40.73, -74.1)                                  <2>
+    .bottomRight(40.717, -73.99);                           <3>
 --------------------------------------------------
+<1> field
+<2> bounding box top left point
+<3> bounding box bottom right point
 
 Note that you can cache the result using
 `GeoBoundingBoxFilterBuilder#cache(boolean)` method. See
@@ -134,12 +140,18 @@ Distance Filter]
 
 [source,java]
 --------------------------------------------------
-FilterBuilders.geoDistanceFilter("pin.location")
-    .point(40, -70)
-    .distance(200, DistanceUnit.KILOMETERS)
-    .optimizeBbox("memory")                    // Can be also "indexed" or "none"
-    .geoDistance(GeoDistance.ARC);            // Or GeoDistance.PLANE
+FilterBuilder filter = geoDistanceFilter("pin.location")    <1>
+    .point(40, -70)                                         <2>
+    .distance(200, DistanceUnit.KILOMETERS)                 <3>
+    .optimizeBbox("memory")                                 <4>
+    .geoDistance(GeoDistance.ARC);                          <5>
 --------------------------------------------------
+<1> field
+<2> center point
+<3> distance from center point
+<4> optimize bounding box: `memory`, `indexed` or `none`
+<5> distance computation mode: `GeoDistance.SLOPPY_ARC` (default), `GeoDistance.ARC` (slighly more precise but
+    significantly slower) or `GeoDistance.PLANE` (faster, but inaccurate on long distances and close to the poles)
 
 Note that you can cache the result using
 `GeoDistanceFilterBuilder#cache(boolean)` method. See
@@ -154,15 +166,24 @@ Distance Range Filter]
 
 [source,java]
 --------------------------------------------------
-FilterBuilders.geoDistanceRangeFilter("pin.location")
-    .point(40, -70)
-    .from("200km")
-    .to("400km")
-    .includeLower(true)
-    .includeUpper(false)
-    .optimizeBbox("memory")                    // Can be also "indexed" or "none"
-    .geoDistance(GeoDistance.ARC);            // Or GeoDistance.PLANE
---------------------------------------------------
+FilterBuilder filter = geoDistanceRangeFilter("pin.location")   <1>
+    .point(40, -70)                                             <2>
+    .from("200km")                                              <3>
+    .to("400km")                                                <4>
+    .includeLower(true)                                         <5>
+    .includeUpper(false)                                        <6>
+    .optimizeBbox("memory")                                     <7>
+    .geoDistance(GeoDistance.ARC);                              <8>
+--------------------------------------------------
+<1> field
+<2> center point
+<3> starting distance from center point
+<4> ending distance from center point
+<5> include lower value means that `from` is `gt` when `false` or `gte` when `true`
+<6> include upper value means that `to` is `lt` when `false` or `lte` when `true`
+<7> optimize bounding box: `memory`, `indexed` or `none`
+<8> distance computation mode: `GeoDistance.SLOPPY_ARC` (default), `GeoDistance.ARC` (slighly more precise but
+    significantly slower) or `GeoDistance.PLANE` (faster, but inaccurate on long distances and close to the poles)
 
 Note that you can cache the result using
 `GeoDistanceRangeFilterBuilder#cache(boolean)` method. See
@@ -177,11 +198,13 @@ Filter]
 
 [source,java]
 --------------------------------------------------
-FilterBuilders.geoPolygonFilter("pin.location")
-    .addPoint(40, -70)
-    .addPoint(30, -80)
-    .addPoint(20, -90);
+FilterBuilder filter = geoPolygonFilter("pin.location") <1>
+    .addPoint(40, -70)                                  <2>
+    .addPoint(30, -80)                                  <2>
+    .addPoint(20, -90);                                 <2>
 --------------------------------------------------
+<1> field
+<2> add your polygon of points a document should fall within
 
 Note that you can cache the result using
 `GeoPolygonFilterBuilder#cache(boolean)` method. See
@@ -203,13 +226,13 @@ to your classpath in order to use this type:
 <dependency>
     <groupId>com.spatial4j</groupId>
     <artifactId>spatial4j</artifactId>
-    <version>0.3</version>
+    <version>0.4.1</version>                        <1>
 </dependency>
 
 <dependency>
     <groupId>com.vividsolutions</groupId>
     <artifactId>jts</artifactId>
-    <version>1.12</version>
+    <version>1.13</version>                         <2>
     <exclusions>
         <exclusion>
             <groupId>xerces</groupId>
@@ -218,6 +241,8 @@ to your classpath in order to use this type:
     </exclusions>
 </dependency>
 -----------------------------------------------
+<1> check for updates in http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.spatial4j%22%20AND%20a%3A%22spatial4j%22[Maven Central]
+<2> check for updates in http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.vividsolutions%22%20AND%20a%3A%22jts%22[Maven Central]
 
 [source,java]
 --------------------------------------------------
@@ -233,19 +258,42 @@ import org.elasticsearch.common.geo.ShapeRelation;
 [source,java]
 --------------------------------------------------
 // Shape within another
-filter = FilterBuilders.geoShapeFilter("location",
-    new RectangleImpl(0,10,0,10,SpatialContext.GEO))
-    .relation(ShapeRelation.WITHIN);
+FilterBuilder filter = geoShapeFilter(
+        "location",                                     <1>
+        new RectangleImpl(0,10,0,10,SpatialContext.GEO) <2>
+    )
+    .relation(ShapeRelation.WITHIN);                    <3>
+--------------------------------------------------
+<1> field
+<2> shape
+<3> relation
 
+[source,java]
+--------------------------------------------------
 // Intersect shapes
-filter = FilterBuilders.geoShapeFilter("location",
-    new PointImpl(0, 0, SpatialContext.GEO))
-    .relation(ShapeRelation.INTERSECTS);
+FilterBuilder filter = geoShapeFilter(
+        "location",                                     <1>
+        new PointImpl(0, 0, SpatialContext.GEO)         <2>
+    )
+    .relation(ShapeRelation.INTERSECTS);                <3>
+--------------------------------------------------
+<1> field
+<2> shape
+<3> relation
 
+[source,java]
+--------------------------------------------------
 // Using pre-indexed shapes
-filter = FilterBuilders.geoShapeFilter("location", "New Zealand", "countries")
-    .relation(ShapeRelation.DISJOINT);
+FilterBuilder filter = geoShapeFilter(
+        "location",                                     <1>
+        "New Zealand",                                  <2>
+        "countries")                                    <3>
+    .relation(ShapeRelation.DISJOINT);                  <4>
 --------------------------------------------------
+<1> field
+<2> indexed shape id
+<3> index type of the indexed shapes
+<4> relation
 
 
 [[has-child-parent-filter]]
@@ -258,13 +306,24 @@ See:
 [source,java]
 --------------------------------------------------
 // Has Child
-FilterBuilders.hasChildFilter("blog_tag",
-    QueryBuilders.termQuery("tag", "something"));
+QueryBuilder qb = hasChildFilter(
+    "blog_tag",                     <1>
+    termFilter("tag","something")   <2>
+);
+--------------------------------------------------
+<1> child type to query against
+<2> filter (could be also a query)
 
+[source,java]
+--------------------------------------------------
 // Has Parent
-FilterBuilders.hasParentFilter("blog",
-    QueryBuilders.termQuery("tag", "something"));
+QueryBuilder qb = hasParentFilter(
+    "blog",                         <1>
+    termFilter("tag","something")   <2>
+);
 --------------------------------------------------
+<1> parent type to query against
+<2> filter (could be also a query)
 
 
 [[match-all-filter]]
@@ -274,7 +333,7 @@ See {ref}/query-dsl-match-all-filter.html[Match All Filter]
 
 [source,java]
 --------------------------------------------------
-FilterBuilders.matchAllFilter();
+FilterBuilder filter = matchAllFilter();
 --------------------------------------------------
 
 
@@ -286,11 +345,13 @@ See {ref}/query-dsl-missing-filter.html[Missing Filter]
 
 [source,java]
 --------------------------------------------------
-FilterBuilders.missingFilter("user")
-    .existence(true)
-    .nullValue(true);
+FilterBuilder filter = missingFilter("user")    <1>
+    .existence(true)                            <2>
+    .nullValue(true);                           <3>
 --------------------------------------------------
-
+<1> field
+<2> find missing field that doesn’t exist
+<3> find missing field with an explicit `null` value
 
 [[not-filter]]
 === Not Filter
@@ -300,9 +361,11 @@ See {ref}/query-dsl-not-filter.html[Not Filter]
 
 [source,java]
 --------------------------------------------------
-FilterBuilders.notFilter(
-    FilterBuilders.rangeFilter("price").from("1").to("2"));
+FilterBuilder filter = notFilter(
+    rangeFilter("price").from("1").to("2")  <1>
+);
 --------------------------------------------------
+<1> filter
 
 
 [[or-filter]]
@@ -313,11 +376,12 @@ See {ref}/query-dsl-or-filter.html[Or Filter]
 
 [source,java]
 --------------------------------------------------
-FilterBuilders.orFilter(
-        FilterBuilders.termFilter("name.second", "banon"),
-        FilterBuilders.termFilter("name.nick", "kimchy")
+FilterBuilder filter = orFilter(
+        termFilter("name.second", "banon"), <1>
+        termFilter("name.nick", "kimchy")   <1>
     );
 --------------------------------------------------
+<1> filters
 
 Note that you can cache the result using
 `OrFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>.
@@ -331,8 +395,13 @@ See {ref}/query-dsl-prefix-filter.html[Prefix Filter]
 
 [source,java]
 --------------------------------------------------
-FilterBuilders.prefixFilter("user", "ki");
+FilterBuilder filter = prefixFilter(
+    "user", <1>
+    "ki"    <2>
+);
 --------------------------------------------------
+<1> field
+<2> prefix
 
 Note that you can cache the result using
 `PrefixFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>.
@@ -346,10 +415,11 @@ See {ref}/query-dsl-query-filter.html[Query Filter]
 
 [source,java]
 --------------------------------------------------
-FilterBuilders.queryFilter(
-        QueryBuilders.queryString("this AND that OR thus")
+FilterBuilder filter = queryFilter(
+        queryString("this AND that OR thus")    <1>
     );
 --------------------------------------------------
+<1> query you want to wrap as a filter
 
 Note that you can cache the result using
 `QueryFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>.
@@ -363,17 +433,28 @@ See {ref}/query-dsl-range-filter.html[Range Filter]
 
 [source,java]
 --------------------------------------------------
-FilterBuilders.rangeFilter("age")
-    .from("10")
-    .to("20")
-    .includeLower(true)
-    .includeUpper(false);
+FilterBuilder filter = rangeFilter("age")   <1>
+    .from("10")                             <2>
+    .to("20")                               <3>
+    .includeLower(true)                     <4>
+    .includeUpper(false);                   <5>
+--------------------------------------------------
+<1> field
+<2> from
+<3> to
+<4> include lower value means that `from` is `gt` when `false` or `gte` when `true`
+<5> include upper value means that `to` is `lt` when `false` or `lte` when `true`
 
+[source,java]
+--------------------------------------------------
 // A simplified form using gte, gt, lt or lte
-FilterBuilders.rangeFilter("age")
-    .gte("10")
-    .lt("20");
+FilterBuilder filter = rangeFilter("age")   <1>
+    .gte("10")                              <2>
+    .lt("20");                              <3>
 --------------------------------------------------
+<1> field
+<2> set `from` to 10 and `includeLower` to true
+<3> set `to` to 20 and `includeUpper` to false
 
 Note that you can ask not to cache the result using
 `RangeFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>.
@@ -387,10 +468,12 @@ See {ref}/query-dsl-script-filter.html[Script Filter]
 
 [source,java]
 --------------------------------------------------
-FilterBuilder filter = FilterBuilders.scriptFilter(
-        "doc['age'].value > param1"
-    ).addParam("param1", 10);
+FilterBuilder filter = scriptFilter(
+        "doc['age'].value > param1" <1>
+    ).addParam("param1", 10);       <2>
 --------------------------------------------------
+<1> script to execute
+<2> parameters
 
 Note that you can cache the result using
 `ScriptFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>.
@@ -404,8 +487,13 @@ See {ref}/query-dsl-term-filter.html[Term Filter]
 
 [source,java]
 --------------------------------------------------
-FilterBuilders.termFilter("user", "kimchy");
+FilterBuilder filter = termFilter(
+    "user",     <1>
+    "kimchy"    <2>
+);
 --------------------------------------------------
+<1> field
+<2> value
 
 Note that you can ask not to cache the result using
 `TermFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>.
@@ -419,10 +507,17 @@ See {ref}/query-dsl-terms-filter.html[Terms Filter]
 
 [source,java]
 --------------------------------------------------
-FilterBuilders.termsFilter("user", "kimchy", "elasticsearch")
+FilterBuilder filter = termsFilter(
+        "user",             <1>
+        "kimchy",           <2>
+        "elasticsearch"     <2>
+    )
     .execution("plain");     // Optional, can be also "bool", "and" or "or"
                             // or "bool_nocache", "and_nocache" or "or_nocache"
 --------------------------------------------------
+<1> field
+<2> terms
+<3> execution mode: could be `plain`, `fielddata`, `bool`, `and`, `or`, `bool_nocache`, `and_nocache` or `or_nocache`
 
 Note that you can ask not to cache the result using
 `TermsFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>.
@@ -436,12 +531,14 @@ See {ref}/query-dsl-nested-filter.html[Nested Filter]
 
 [source,java]
 --------------------------------------------------
-FilterBuilders.nestedFilter("obj1",
-    QueryBuilders.boolQuery()
-        .must(QueryBuilders.matchQuery("obj1.name", "blue"))
-        .must(QueryBuilders.rangeQuery("obj1.count").gt(5))
+FilterBuilder filter = nestedFilter("obj1",                     <1>
+    boolFilter()                                                <2>
+        .must(termFilter("obj1.name", "blue"))
+        .must(rangeFilter("obj1.count").gt(5))
     );
 --------------------------------------------------
+<1> path to nested document
+<2> filter
 
 Note that you can ask not to cache the result using
 `NestedFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>.
@@ -454,9 +551,10 @@ tuning control using `cache(boolean)` method when exists.  For example:
 
 [source,java]
 --------------------------------------------------
-FilterBuilder filter = FilterBuilders.andFilter(
-        FilterBuilders.rangeFilter("postDate").from("2010-03-01").to("2010-04-01"),
-        FilterBuilders.prefixFilter("name.second", "ba")
-        )
-    .cache(true);
+FilterBuilder filter = andFilter(
+        rangeFilter("postDate").from("2010-03-01").to("2010-04-01"),
+        prefixFilter("name.second", "ba")
+    )
+    .cache(true);   <1>
 --------------------------------------------------
+<1> force caching filter

docs/java-api/query-dsl-queries.asciidoc

@@ -8,11 +8,12 @@ builders is `QueryBuilders`. Once your query is ready, you can use the
 
 See also how to build <<query-dsl-filters,Filters>>
 
-To use `QueryBuilders` just import them in your class:
+To use `QueryBuilders` or `FilterBuilders` just import them in your class:
 
 [source,java]
 --------------------------------------------------
-import org.elasticsearch.index.query.QueryBuilders.*;
+import static org.elasticsearch.index.query.QueryBuilders.*;
+import static org.elasticsearch.index.query.FilterBuilders.*;
 --------------------------------------------------
 
 Note that you can easily print (aka debug) JSON generated queries using
@@ -27,11 +28,15 @@ such as `count` and `search`.
 
 See {ref}/query-dsl-match-query.html[Match Query]
 
-
 [source,java]
 --------------------------------------------------
-QueryBuilder qb = QueryBuilders.matchQuery("name", "kimchy elasticsearch");
+QueryBuilder qb = matchQuery(
+    "name",                  <1>
+    "kimchy elasticsearch"   <2>
+);
 --------------------------------------------------
+<1> field
+<2> text
 
 
 [[multimatch]]
@@ -42,11 +47,13 @@ Query]
 
 [source,java]
 --------------------------------------------------
-QueryBuilder qb = QueryBuilders.multiMatchQuery(
-    "kimchy elasticsearch",     // Text you are looking for
-    "user", "message"           // Fields you query on
-    );
+QueryBuilder qb = multiMatchQuery(
+    "kimchy elasticsearch", <1>
+    "user", "message"       <2>
+);
 --------------------------------------------------
+<1> text
+<2> fields
 
 
 [[bool]]
@@ -54,16 +61,17 @@ QueryBuilder qb = QueryBuilders.multiMatchQuery(
 
 See {ref}/query-dsl-bool-query.html[Boolean Query]
 
-
 [source,java]
 --------------------------------------------------
-QueryBuilder qb = QueryBuilders
-                    .boolQuery()
-                    .must(termQuery("content", "test1"))
-                    .must(termQuery("content", "test4"))
-                    .mustNot(termQuery("content", "test2"))
-                    .should(termQuery("content", "test3"));
+QueryBuilder qb = boolQuery()
+    .must(termQuery("content", "test1"))    <1>
+    .must(termQuery("content", "test4"))    <1>
+    .mustNot(termQuery("content", "test2")) <2>
+    .should(termQuery("content", "test3")); <3>
 --------------------------------------------------
+<1> must query
+<2> must not query
+<3> should query
 
 
 [[boosting]]
@@ -71,26 +79,27 @@ QueryBuilder qb = QueryBuilders
 
 See {ref}/query-dsl-boosting-query.html[Boosting Query]
 
-
 [source,java]
 --------------------------------------------------
-QueryBuilders.boostingQuery()
-            .positive(QueryBuilders.termQuery("name","kimchy"))
-            .negative(QueryBuilders.termQuery("name","dadoonet"))
-            .negativeBoost(0.2f);
+QueryBuilder qb = boostingQuery()
+    .positive(termQuery("name","kimchy"))   <1>
+    .negative(termQuery("name","dadoonet")) <2>
+    .negativeBoost(0.2f);                   <3>
 --------------------------------------------------
-
+<1> query that will promote documents
+<2> query that will demote documents
+<3> negative boost
 
 [[ids]]
 === IDs Query
 
 See {ref}/query-dsl-ids-query.html[IDs Query]
 
-
 [source,java]
 --------------------------------------------------
-QueryBuilders.idsQuery().ids("1", "2");
+QueryBuilder qb = idsQuery().ids("1", "2"); <1>
 --------------------------------------------------
+<1> document ids
 
 [[constant-score]]
 === Constant Score Query
@@ -100,15 +109,23 @@ Score Query]
 
 [source,java]
 --------------------------------------------------
-// Using with Filters
-QueryBuilders.constantScoreQuery(FilterBuilders.termFilter("name","kimchy"))
-                .boost(2.0f);
-
-// With Queries
-QueryBuilders.constantScoreQuery(QueryBuilders.termQuery("name","kimchy"))
-                .boost(2.0f);
+QueryBuilder qb = constantScoreQuery(
+        termFilter("name","kimchy")     <1>
+    )
+    .boost(2.0f);                       <2>
 --------------------------------------------------
+<1> you can use a filter
+<2> filter score
 
+[source,java]
+--------------------------------------------------
+QueryBuilder qb = constantScoreQuery(
+        termQuery("name","kimchy")      <1>
+    )
+    .boost(2.0f);                       <2>
+--------------------------------------------------
+<1> you can use a query
+<2> query score
 
 [[dismax]]
 === Disjunction Max Query
@@ -118,12 +135,16 @@ Query]
 
 [source,java]
 --------------------------------------------------
-QueryBuilders.disMaxQuery()
-                .add(QueryBuilders.termQuery("name","kimchy"))          // Your queries
-                .add(QueryBuilders.termQuery("name","elasticsearch"))   // Your queries
-                .boost(1.2f)
-                .tieBreaker(0.7f);
+QueryBuilder qb = disMaxQuery()
+    .add(termQuery("name","kimchy"))        <1>
+    .add(termQuery("name","elasticsearch")) <2>
+    .boost(1.2f)                            <3>
+    .tieBreaker(0.7f);                      <4>
 --------------------------------------------------
+<1> add your queries
+<2> add your queries
+<3> boost factor
+<4> tie breaker
 
 
 [[flt]]
@@ -135,17 +156,23 @@ See:
 
 [source,java]
 --------------------------------------------------
-// flt Query
-QueryBuilders.fuzzyLikeThisQuery("name.first", "name.last")     // Fields
-                .likeText("text like this one")                 // Text
-                .maxQueryTerms(12);                             // Max num of Terms
-                                                                // in generated queries
+QueryBuilder qb = fuzzyLikeThisQuery("name.first", "name.last") <1>
+    .likeText("text like this one")                             <2>
+    .maxQueryTerms(12);                                         <3>
+--------------------------------------------------
+<1> fields
+<2> text
+<3> max num of Terms in generated queries
 
-// flt_field Query
-QueryBuilders.fuzzyLikeThisFieldQuery("name.first")             // Only on single field
-                .likeText("text like this one")
-                .maxQueryTerms(12);
+[source,java]
+--------------------------------------------------
+QueryBuilder qb = fuzzyLikeThisFieldQuery("name.first")         <1>
+                .likeText("text like this one")                 <2>
+                .maxQueryTerms(12);                             <3>
 --------------------------------------------------
+<1> field
+<2> text
+<3> max num of Terms in generated queries
 
 
 [[fuzzy]]
@@ -153,11 +180,15 @@ QueryBuilders.fuzzyLikeThisFieldQuery("name.first")             // Only on singl
 
 See {ref}/query-dsl-fuzzy-query.html[Fuzzy Query]
 
-
 [source,java]
 --------------------------------------------------
-QueryBuilder qb = QueryBuilders.fuzzyQuery("name", "kimzhy");
+QueryBuilder qb = fuzzyQuery(
+    "name",     <1>
+    "kimzhy"    <2>
+);
 --------------------------------------------------
+<1> field
+<2> text
 
 
 [[has-child-parent]]
@@ -170,13 +201,24 @@ See:
 [source,java]
 --------------------------------------------------
 // Has Child
-QueryBuilders.hasChildQuery("blog_tag",
-                QueryBuilders.termQuery("tag","something"))
+QueryBuilder qb = hasChildQuery(
+    "blog_tag",                     <1>
+    termQuery("tag","something")    <2>
+);
+--------------------------------------------------
+<1> child type to query against
+<2> query (could be also a filter)
 
 // Has Parent
-QueryBuilders.hasParentQuery("blog",
-                QueryBuilders.termQuery("tag","something"));
+[source,java]
+--------------------------------------------------
+QueryBuilder qb = hasParentQuery(
+    "blog",                         <1>
+    termQuery("tag","something")    <2>
+);
 --------------------------------------------------
+<1> parent type to query against
+<2> query (could be also a filter)
 
 
 [[match-all]]
@@ -187,7 +229,7 @@ Query]
 
 [source,java]
 --------------------------------------------------
-QueryBuilder qb = QueryBuilders.matchAllQuery();
+QueryBuilder qb = matchAllQuery();
 --------------------------------------------------
 
 
@@ -201,18 +243,28 @@ See:
 [source,java]
 --------------------------------------------------
 // mlt Query
-QueryBuilders.moreLikeThisQuery("name.first", "name.last")      // Fields
-                .likeText("text like this one")                 // Text
-                .minTermFreq(1)                                 // Ignore Threshold
-                .maxQueryTerms(12);                             // Max num of Terms
-                                                                // in generated queries
+QueryBuilder qb = moreLikeThisQuery("name.first", "name.last")  <1>
+    .likeText("text like this one")                             <2>
+    .minTermFreq(1)                                             <3>
+    .maxQueryTerms(12);                                         <4>
+--------------------------------------------------
+<1> fields
+<2> text
+<3> ignore threshold
+<4> max num of Terms in generated queries
 
+[source,java]
+--------------------------------------------------
 // mlt_field Query
-QueryBuilders.moreLikeThisFieldQuery("name.first")              // Only on single field
-                .likeText("text like this one")
-                .minTermFreq(1)
-                .maxQueryTerms(12);
+QueryBuilder qb = moreLikeThisFieldQuery("name.first")          <1>
+    .likeText("text like this one")                             <2>
+    .minTermFreq(1)                                             <3>
+    .maxQueryTerms(12);                                         <4>
 --------------------------------------------------
+<1> field
+<2> text
+<3> ignore threshold
+<4> max num of Terms in generated queries
 
 
 [[prefix]]
@@ -222,8 +274,13 @@ See {ref}/query-dsl-prefix-query.html[Prefix Query]
 
 [source,java]
 --------------------------------------------------
-QueryBuilders.prefixQuery("brand", "heine");
+QueryBuilder qb = prefixQuery(
+    "brand",    <1>
+    "heine"     <2>
+);
 --------------------------------------------------
+<1> field
+<2> prefix
 
 
 [[query-string]]
@@ -233,8 +290,9 @@ See {ref}/query-dsl-query-string-query.html[QueryString Query]
 
 [source,java]
 --------------------------------------------------
-QueryBuilder qb = QueryBuilders.queryString("+kimchy -elasticsearch");
+QueryBuilder qb = queryString("+kimchy -elasticsearch");    <1>
 --------------------------------------------------
+<1> text
 
 
 [[java-range]]
@@ -244,55 +302,85 @@ See {ref}/query-dsl-range-query.html[Range Query]
 
 [source,java]
 --------------------------------------------------
-QueryBuilder qb = QueryBuilders
-                    .rangeQuery("price")
-                    .from(5)
-                    .to(10)
-                    .includeLower(true)
-                    .includeUpper(false);
+QueryBuilder qb = rangeQuery("price")   <1>
+    .from(5)                            <2>
+    .to(10)                             <3>
+    .includeLower(true)                 <4>
+    .includeUpper(false);               <5>
 --------------------------------------------------
+<1> field
+<2> from
+<3> to
+<4> include lower value means that `from` is `gt` when `false` or `gte` when `true`
+<5> include upper value means that `to` is `lt` when `false` or `lte` when `true`
 
 
 === Span Queries (first, near, not, or, term)
 
 See:
+ * {ref}/query-dsl-span-term-query.html[Span Term Query]
  * {ref}/query-dsl-span-first-query.html[Span First Query]
  * {ref}/query-dsl-span-near-query.html[Span Near Query]
  * {ref}/query-dsl-span-not-query.html[Span Not Query]
  * {ref}/query-dsl-span-or-query.html[Span Or Query]
- * {ref}/query-dsl-span-term-query.html[Span Term Query]
+
+[source,java]
+--------------------------------------------------
+// Span Term
+QueryBuilder qb = spanTermQuery(
+    "user",                                     <1>
+    "kimchy"                                    <2>
+);
+--------------------------------------------------
+<1> field
+<2> value
 
 [source,java]
 --------------------------------------------------
 // Span First
-QueryBuilders.spanFirstQuery(
-                QueryBuilders.spanTermQuery("user", "kimchy"),  // Query
-                3                                               // Max End position
-        );
+QueryBuilder qb = spanFirstQuery(
+    spanTermQuery("user", "kimchy"),            <1>
+    3                                           <2>
+);
+--------------------------------------------------
+<1> query
+<2> max end position
 
+[source,java]
+--------------------------------------------------
 // Span Near
-QueryBuilders.spanNearQuery()
-    .clause(QueryBuilders.spanTermQuery("field","value1"))  // Span Term Queries
-    .clause(QueryBuilders.spanTermQuery("field","value2"))
-    .clause(QueryBuilders.spanTermQuery("field","value3"))
-    .slop(12)                                               // Slop factor
-    .inOrder(false)
-    .collectPayloads(false);
+QueryBuilder qb = spanNearQuery()
+    .clause(spanTermQuery("field","value1"))    <1>
+    .clause(spanTermQuery("field","value2"))    <1>
+    .clause(spanTermQuery("field","value3"))    <1>
+    .slop(12)                                   <2>
+    .inOrder(false)                             <3>
+    .collectPayloads(false);                    <4>
+--------------------------------------------------
+<1> span term queries
+<2> slop factor: the maximum number of intervening unmatched positions
+<3> whether matches are required to be in-order
+<4> collect payloads or not
 
+[source,java]
+--------------------------------------------------
 // Span Not
-QueryBuilders.spanNotQuery()
-    .include(QueryBuilders.spanTermQuery("field","value1"))
-    .exclude(QueryBuilders.spanTermQuery("field","value2"));
+QueryBuilder qb = spanNotQuery()
+    .include(spanTermQuery("field","value1"))   <1>
+    .exclude(spanTermQuery("field","value2"));  <2>
+--------------------------------------------------
+<1> span query whose matches are filtered
+<2> span query whose matches must not overlap those returned
 
+[source,java]
+--------------------------------------------------
 // Span Or
-QueryBuilders.spanOrQuery()
-    .clause(QueryBuilders.spanTermQuery("field","value1"))
-    .clause(QueryBuilders.spanTermQuery("field","value2"))
-    .clause(QueryBuilders.spanTermQuery("field","value3"));
-
-// Span Term
-QueryBuilders.spanTermQuery("user","kimchy");
+QueryBuilder qb = spanOrQuery()
+    .clause(spanTermQuery("field","value1"))    <1>
+    .clause(spanTermQuery("field","value2"))    <1>
+    .clause(spanTermQuery("field","value3"));   <1>
 --------------------------------------------------
+<1> span term queries
 
 
 [[term]]
@@ -302,9 +390,12 @@ See {ref}/query-dsl-term-query.html[Term Query]
 
 [source,java]
 --------------------------------------------------
-QueryBuilder qb = QueryBuilders.termQuery("name", "kimchy");
+QueryBuilder qb = termQuery(
+    "name",     <1>
+    "kimchy");  <2>
 --------------------------------------------------
-
+<1> field
+<2> value
 
 [[java-terms]]
 === Terms Query
@@ -313,11 +404,13 @@ See {ref}/query-dsl-terms-query.html[Terms Query]
 
 [source,java]
 --------------------------------------------------
-QueryBuilders.termsQuery("tags",    // field
-    "blue", "pill")                 // values
-    .minimumMatch(1);               // How many terms must match
+QueryBuilder qb = termsQuery("tags",    <1>
+    "blue", "pill")                 <2>
+    .minimumMatch(1);               <3>
 --------------------------------------------------
-
+<1> field
+<2> values
+<3> how many terms must match at least
 
 [[top-children]]
 === Top Children Query
@@ -326,68 +419,80 @@ See {ref}/query-dsl-top-children-query.html[Top Children Query]
 
 [source,java]
 --------------------------------------------------
-QueryBuilders.topChildrenQuery(
-        "blog_tag",                                 // field
-        QueryBuilders.termQuery("tag", "something") // Query
+QueryBuilder qb = topChildrenQuery(
+        "blog_tag",                   <1>
+        termQuery("tag", "something") <2>
     )
-    .score("max")                                   // max, sum or avg
-    .factor(5)
-    .incrementalFactor(2);
+    .score("max")                     <3>
+    .factor(5)                        <4>
+    .incrementalFactor(2);            <5>
 --------------------------------------------------
-
+<1> field
+<2> query
+<3> `max`, `sum` or `avg`
+<4> how many hits are asked for in the first child query run (defaults to 5)
+<5> if not enough parents are found, and there are still more child docs to query, then the child search hits are
+    expanded by multiplying by the incremental_factor (defaults to 2).
 
 [[wildcard]]
 === Wildcard Query
 
 See {ref}/query-dsl-wildcard-query.html[Wildcard Query]
 
-
 [source,java]
 --------------------------------------------------
-QueryBuilders.wildcardQuery("user", "k?mc*");
+QueryBuilder qb = wildcardQuery("user", "k?mc*");
 --------------------------------------------------
 
-
 [[nested]]
 === Nested Query
 
 See {ref}/query-dsl-nested-query.html[Nested Query]
 
-
 [source,java]
 --------------------------------------------------
-QueryBuilders.nestedQuery("obj1",               // Path
-                QueryBuilders.boolQuery()       // Your query
-                        .must(QueryBuilders.matchQuery("obj1.name", "blue"))
-                        .must(QueryBuilders.rangeQuery("obj1.count").gt(5))
-            )
-            .scoreMode("avg");                  // max, total, avg or none
+QueryBuilder qb = nestedQuery(
+        "obj1",               <1>
+        boolQuery()           <2>
+                .must(matchQuery("obj1.name", "blue"))
+                .must(rangeQuery("obj1.count").gt(5))
+    )
+    .scoreMode("avg");        <3>
 --------------------------------------------------
-
-
+<1> path to nested document
+<2> your query. Any fields referenced inside the query must use the complete path (fully qualified).
+<3> score mode could be `max`, `total`, `avg` (default) or `none`
 
 [[indices]]
 === Indices Query
 
 See {ref}/query-dsl-indices-query.html[Indices Query]
 
-
 [source,java]
 --------------------------------------------------
 // Using another query when no match for the main one
-QueryBuilders.indicesQuery(
-                QueryBuilders.termQuery("tag", "wow"),
-                "index1", "index2"
-            )
-            .noMatchQuery(QueryBuilders.termQuery("tag", "kow"));
+QueryBuilder qb = indicesQuery(
+        termQuery("tag", "wow"),            <1>
+        "index1", "index2"                  <2>
+    )
+    .noMatchQuery(termQuery("tag", "kow")); <3>
+--------------------------------------------------
+<1> query to be executed on selected indices
+<2> selected indices
+<3> query to be executed on non matching indices
 
+[source,java]
+--------------------------------------------------
 // Using all (match all) or none (match no documents)
-QueryBuilders.indicesQuery(
-                QueryBuilders.termQuery("tag", "wow"),
-                "index1", "index2"
-            )
-            .noMatchQuery("all");       // all or none
+QueryBuilder qb = indicesQuery(
+        termQuery("tag", "wow"),            <1>
+        "index1", "index2"                  <2>
+    )
+    .noMatchQuery("all");                   <3>
 --------------------------------------------------
+<1> query to be executed on selected indices
+<2> selected indices
+<3> `none` (to match no documents), and `all` (to match all documents). Defaults to `all`.
 
 
 [[geo-shape]]
@@ -395,23 +500,22 @@ QueryBuilders.indicesQuery(
 
 See {ref}/query-dsl-geo-shape-query.html[GeoShape Query]
 
-
 Note: the `geo_shape` type uses `Spatial4J` and `JTS`, both of which are
 optional dependencies. Consequently you must add `Spatial4J` and `JTS`
 to your classpath in order to use this type:
 
-[source,java]
+[source,xml]
 --------------------------------------------------
 <dependency>
     <groupId>com.spatial4j</groupId>
     <artifactId>spatial4j</artifactId>
-    <version>0.3</version>
+    <version>0.4.1</version>                        <1>
 </dependency>
 
 <dependency>
     <groupId>com.vividsolutions</groupId>
     <artifactId>jts</artifactId>
-    <version>1.12</version>
+    <version>1.13</version>                         <2>
     <exclusions>
         <exclusion>
             <groupId>xerces</groupId>
@@ -420,6 +524,8 @@ to your classpath in order to use this type:
     </exclusions>
 </dependency>
 --------------------------------------------------
+<1> check for updates in http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.spatial4j%22%20AND%20a%3A%22spatial4j%22[Maven Central]
+<2> check for updates in http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.vividsolutions%22%20AND%20a%3A%22jts%22[Maven Central]
 
 [source,java]
 --------------------------------------------------
@@ -435,16 +541,39 @@ import org.elasticsearch.common.geo.ShapeRelation;
 [source,java]
 --------------------------------------------------
 // Shape within another
-QueryBuilders.geoShapeQuery("location",
-                new RectangleImpl(0,10,0,10,SpatialContext.GEO))
-            .relation(ShapeRelation.WITHIN);
+QueryBuilder qb = geoShapeQuery(
+        "location",                                     <1>
+        new RectangleImpl(0,10,0,10,SpatialContext.GEO) <2>
+    )
+    .relation(ShapeRelation.WITHIN);                    <3>
+--------------------------------------------------
+<1> field
+<2> shape
+<3> relation
 
+[source,java]
+--------------------------------------------------
 // Intersect shapes
-QueryBuilders.geoShapeQuery("location",
-                new PointImpl(0, 0, SpatialContext.GEO))
-            .relation(ShapeRelation.INTERSECTS);
+QueryBuilder qb = geoShapeQuery(
+        "location",                                     <1>
+        new PointImpl(0, 0, SpatialContext.GEO)         <2>
+    )
+    .relation(ShapeRelation.INTERSECTS);                <3>
+--------------------------------------------------
+<1> field
+<2> shape
+<3> relation
 
-// Using pre-indexed shapes
-QueryBuilders.geoShapeQuery("location", "New Zealand", "countries")
-            .relation(ShapeRelation.DISJOINT);
+[source,java]
 --------------------------------------------------
+// Using pre-indexed shapes
+QueryBuilder qb = geoShapeQuery(
+        "location",                                     <1>
+        "New Zealand",                                  <2>
+        "countries")                                    <3>
+    .relation(ShapeRelation.DISJOINT);                  <4>
+--------------------------------------------------
+<1> field
+<2> indexed shape id
+<3> index type of the indexed shapes
+<4> relation