Build that java api docs from a test (#24354)

We've had `QueryDSLDocumentationTests` for a while but it had a very
hopeful comment at the top about how we want to make sure that the
example in the query-dsl docs match up with the test but we never
had anything that made *sure* that they did. This changes that!

Now the examples from the query-dsl docs are all built from the
`QueryDSLDocumentationTests`. All except for the percolator example
because that is hard to do as it stands now.

To make this easier this change moves `QueryDSLDocumentationTests`
from core and into the high level rest client. This is useful for
two reasons:
1. We expect the high level rest client to be able to use the builders.
2. The code that builds that docs doesn't check out all of
Elasticsearch. It only checks out certain directories. Since we're
already including snippets from that directory we don't have to
make any changes to that process.

Closes #24320

client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java

@@ -0,0 +1,453 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.client.documentation;
+
+import org.apache.lucene.search.join.ScoreMode;
+import org.elasticsearch.common.geo.GeoPoint;
+import org.elasticsearch.common.geo.ShapeRelation;
+import org.elasticsearch.common.geo.builders.CoordinatesBuilder;
+import org.elasticsearch.common.geo.builders.ShapeBuilders;
+import org.elasticsearch.common.unit.DistanceUnit;
+import org.elasticsearch.index.query.GeoShapeQueryBuilder;
+import org.elasticsearch.index.query.functionscore.FunctionScoreQueryBuilder;
+import org.elasticsearch.index.query.functionscore.FunctionScoreQueryBuilder.FilterFunctionBuilder;
+import org.elasticsearch.script.Script;
+import org.elasticsearch.script.ScriptType;
+import org.elasticsearch.test.ESTestCase;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import static java.util.Collections.singletonMap;
+import static org.elasticsearch.index.query.QueryBuilders.boolQuery;
+import static org.elasticsearch.index.query.QueryBuilders.boostingQuery;
+import static org.elasticsearch.index.query.QueryBuilders.commonTermsQuery;
+import static org.elasticsearch.index.query.QueryBuilders.constantScoreQuery;
+import static org.elasticsearch.index.query.QueryBuilders.disMaxQuery;
+import static org.elasticsearch.index.query.QueryBuilders.existsQuery;
+import static org.elasticsearch.index.query.QueryBuilders.functionScoreQuery;
+import static org.elasticsearch.index.query.QueryBuilders.fuzzyQuery;
+import static org.elasticsearch.index.query.QueryBuilders.geoBoundingBoxQuery;
+import static org.elasticsearch.index.query.QueryBuilders.geoDistanceQuery;
+import static org.elasticsearch.index.query.QueryBuilders.geoPolygonQuery;
+import static org.elasticsearch.index.query.QueryBuilders.geoShapeQuery;
+import static org.elasticsearch.index.query.QueryBuilders.hasChildQuery;
+import static org.elasticsearch.index.query.QueryBuilders.hasParentQuery;
+import static org.elasticsearch.index.query.QueryBuilders.idsQuery;
+import static org.elasticsearch.index.query.QueryBuilders.matchAllQuery;
+import static org.elasticsearch.index.query.QueryBuilders.matchQuery;
+import static org.elasticsearch.index.query.QueryBuilders.moreLikeThisQuery;
+import static org.elasticsearch.index.query.QueryBuilders.multiMatchQuery;
+import static org.elasticsearch.index.query.QueryBuilders.nestedQuery;
+import static org.elasticsearch.index.query.QueryBuilders.prefixQuery;
+import static org.elasticsearch.index.query.QueryBuilders.queryStringQuery;
+import static org.elasticsearch.index.query.QueryBuilders.rangeQuery;
+import static org.elasticsearch.index.query.QueryBuilders.regexpQuery;
+import static org.elasticsearch.index.query.QueryBuilders.scriptQuery;
+import static org.elasticsearch.index.query.QueryBuilders.simpleQueryStringQuery;
+import static org.elasticsearch.index.query.QueryBuilders.spanContainingQuery;
+import static org.elasticsearch.index.query.QueryBuilders.spanFirstQuery;
+import static org.elasticsearch.index.query.QueryBuilders.spanMultiTermQueryBuilder;
+import static org.elasticsearch.index.query.QueryBuilders.spanNearQuery;
+import static org.elasticsearch.index.query.QueryBuilders.spanNotQuery;
+import static org.elasticsearch.index.query.QueryBuilders.spanOrQuery;
+import static org.elasticsearch.index.query.QueryBuilders.spanTermQuery;
+import static org.elasticsearch.index.query.QueryBuilders.spanWithinQuery;
+import static org.elasticsearch.index.query.QueryBuilders.termQuery;
+import static org.elasticsearch.index.query.QueryBuilders.termsQuery;
+import static org.elasticsearch.index.query.QueryBuilders.typeQuery;
+import static org.elasticsearch.index.query.QueryBuilders.wildcardQuery;
+import static org.elasticsearch.index.query.functionscore.ScoreFunctionBuilders.exponentialDecayFunction;
+import static org.elasticsearch.index.query.functionscore.ScoreFunctionBuilders.randomFunction;
+
+/**
+ * Examples of using the transport client that are imported into the transport client documentation.
+ * There are no assertions here because we're mostly concerned with making sure that the examples
+ * compile and don't throw weird runtime exceptions. Assertions and example data would be nice, but
+ * that is secondary.
+ */
+public class QueryDSLDocumentationTests extends ESTestCase {
+    public void testBool() {
+        // tag::bool
+        boolQuery()
+                .must(termQuery("content", "test1"))                 // <1>
+                .must(termQuery("content", "test4"))                 // <1>
+                .mustNot(termQuery("content", "test2"))              // <2>
+                .should(termQuery("content", "test3"))               // <3>
+                .filter(termQuery("content", "test5"));              // <4>
+        // end::bool
+    }
+
+    public void testBoosting() {
+        // tag::boosting
+        boostingQuery(
+                    termQuery("name","kimchy"),                      // <1>
+                    termQuery("name","dadoonet"))                    // <2>
+                .negativeBoost(0.2f);                                // <3>
+        // end::boosting
+    }
+
+    public void testCommonTerms() {
+        // tag::common_terms
+        commonTermsQuery("name",                                     // <1>
+                         "kimchy");                                  // <2>
+        // end::common_terms
+    }
+
+    public void testConstantScore() {
+        // tag::constant_score
+        constantScoreQuery(
+                termQuery("name","kimchy"))                          // <1>
+            .boost(2.0f);                                            // <2>
+        // end::constant_score
+    }
+
+    public void testDisMax() {
+        // tag::dis_max
+        disMaxQuery()
+                .add(termQuery("name", "kimchy"))                    // <1>
+                .add(termQuery("name", "elasticsearch"))             // <2>
+                .boost(1.2f)                                         // <3>
+                .tieBreaker(0.7f);                                   // <4>
+        // end::dis_max
+    }
+
+    public void testExists() {
+        // tag::exists
+        existsQuery("name");   // <1>
+        // end::exists
+    }
+
+    public void testFunctionScore() {
+        // tag::function_score
+        FilterFunctionBuilder[] functions = {
+                new FunctionScoreQueryBuilder.FilterFunctionBuilder(
+                        matchQuery("name", "kimchy"),                // <1>
+                        randomFunction("ABCDEF")),                   // <2>
+                new FunctionScoreQueryBuilder.FilterFunctionBuilder(
+                        exponentialDecayFunction("age", 0L, 1L))     // <3>
+        };
+        functionScoreQuery(functions);
+        // end::function_score
+    }
+
+    public void testFuzzy() {
+        // tag::fuzzy
+        fuzzyQuery(
+                "name",                                              // <1>
+                "kimchy");                                           // <2>
+        // end::fuzzy
+    }
+
+    public void testGeoBoundingBox() {
+        // tag::geo_bounding_box
+        geoBoundingBoxQuery("pin.location")                          // <1>
+            .setCorners(40.73, -74.1,                                // <2>
+                        40.717, -73.99);                             // <3>
+        // end::geo_bounding_box
+    }
+
+    public void testGeoDistance() {
+        // tag::geo_distance
+        geoDistanceQuery("pin.location")                             // <1>
+            .point(40, -70)                                          // <2>
+            .distance(200, DistanceUnit.KILOMETERS);                 // <3>
+        // end::geo_distance
+    }
+
+    public void testGeoPolygon() {
+        // tag::geo_polygon
+        List<GeoPoint> points = new ArrayList<GeoPoint>();           // <1>
+        points.add(new GeoPoint(40, -70));
+        points.add(new GeoPoint(30, -80));
+        points.add(new GeoPoint(20, -90));
+        geoPolygonQuery("pin.location", points);                     // <2>
+        // end::geo_polygon
+    }
+
+    public void testGeoShape() throws IOException {
+        {
+            // tag::geo_shape
+            GeoShapeQueryBuilder qb = geoShapeQuery(
+                    "pin.location",                                      // <1>
+                    ShapeBuilders.newMultiPoint(                         // <2>
+                            new CoordinatesBuilder()
+                        .coordinate(0, 0)
+                        .coordinate(0, 10)
+                        .coordinate(10, 10)
+                        .coordinate(10, 0)
+                        .coordinate(0, 0)
+                        .build()));
+            qb.relation(ShapeRelation.WITHIN);                           // <3>
+            // end::geo_shape
+        }
+
+        {
+            // tag::indexed_geo_shape
+            // Using pre-indexed shapes
+            GeoShapeQueryBuilder qb = geoShapeQuery(
+                        "pin.location",                                  // <1>
+                        "DEU",                                           // <2>
+                        "countries");                                    // <3>
+            qb.relation(ShapeRelation.WITHIN)                            // <4>
+                .indexedShapeIndex("shapes")                             // <5>
+                .indexedShapePath("location");                           // <6>
+            // end::indexed_geo_shape
+        }
+    }
+
+    public void testHasChild() {
+        // tag::has_child
+        hasChildQuery(
+                "blog_tag",                                          // <1>
+                termQuery("tag","something"),                        // <2>
+                ScoreMode.None);                                     // <3>
+        // end::has_child
+    }
+
+    public void testHasParent() {
+        // tag::has_parent
+        hasParentQuery(
+            "blog",                                                  // <1>
+            termQuery("tag","something"),                            // <2>
+            false);                                                  // <3>
+        // end::has_parent
+    }
+
+    public void testIds() {
+        // tag::ids
+        idsQuery("my_type", "type2")
+                .addIds("1", "4", "100");
+
+        idsQuery()                                                   // <1>
+                .addIds("1", "4", "100");
+        // end::ids
+    }
+
+    public void testMatchAll() {
+        // tag::match_all
+        matchAllQuery();
+        // end::match_all
+    }
+
+    public void testMatch() {
+        // tag::match
+        matchQuery(
+                "name",                                              // <1>
+                "kimchy elasticsearch");                             // <2>
+        // end::match
+    }
+
+    public void testMoreLikeThis() {
+        // tag::more_like_this
+        String[] fields = {"name.first", "name.last"};               // <1>
+        String[] texts = {"text like this one"};                     // <2>
+
+        moreLikeThisQuery(fields, texts, null)
+            .minTermFreq(1)                                          // <3>
+            .maxQueryTerms(12);                                      // <4>
+        // end::more_like_this
+    }
+
+    public void testMultiMatch() {
+        // tag::multi_match
+        multiMatchQuery(
+                "kimchy elasticsearch",                              // <1>
+                "user", "message");                                  // <2>
+        // end::multi_match
+    }
+
+    public void testNested() {
+        // tag::nested
+        nestedQuery(
+                "obj1",                                              // <1>
+                boolQuery()                                          // <2>
+                        .must(matchQuery("obj1.name", "blue"))
+                        .must(rangeQuery("obj1.count").gt(5)),
+                ScoreMode.Avg);                                      // <3>
+        // end::nested
+    }
+
+    public void testPrefix() {
+        // tag::prefix
+        prefixQuery(
+                "brand",                                             // <1>
+                "heine");                                            // <2>
+        // end::prefix
+    }
+
+    public void testQueryString() {
+        // tag::query_string
+        queryStringQuery("+kimchy -elasticsearch");
+        // end::query_string
+    }
+
+    public void testRange() {
+        // tag::range
+        rangeQuery("price")                                          // <1>
+            .from(5)                                                 // <2>
+            .to(10)                                                  // <3>
+            .includeLower(true)                                      // <4>
+            .includeUpper(false);                                    // <5>
+        // end::range
+
+        // tag::range_simplified
+        // A simplified form using gte, gt, lt or lte
+        rangeQuery("age")                                             // <1>
+            .gte("10")                                                // <2>
+            .lt("20");                                                // <3>
+        // end::range_simplified
+    }
+
+    public void testRegExp() {
+        // tag::regexp
+        regexpQuery(
+                "name.first",                                        // <1>
+                "s.*y");                                             // <2>
+        // end::regexp
+    }
+
+    public void testScript() {
+        // tag::script_inline
+        scriptQuery(
+                new Script("doc['num1'].value > 1")                  // <1>
+            );
+        // end::script_inline
+
+        // tag::script_file
+        Map<String, Object> parameters = new HashMap<>();
+        parameters.put("param1", 5);
+        scriptQuery(new Script(
+                ScriptType.FILE,                                     // <1>
+                "painless",                                          // <2>
+                "myscript",                                          // <3>
+                singletonMap("param1", 5)));                         // <4>
+        // end::script_file
+    }
+
+    public void testSimpleQueryString() {
+        // tag::simple_query_string
+        simpleQueryStringQuery("+kimchy -elasticsearch");
+        // end::simple_query_string
+    }
+
+    public void testSpanContaining() {
+        // tag::span_containing
+        spanContainingQuery(
+                spanNearQuery(spanTermQuery("field1","bar"), 5)      // <1>
+                    .addClause(spanTermQuery("field1","baz"))
+                    .inOrder(true),
+                spanTermQuery("field1","foo"));                      // <2>
+        // end::span_containing
+    }
+
+    public void testSpanFirst() {
+        // tag::span_first
+        spanFirstQuery(
+                spanTermQuery("user", "kimchy"),                     // <1>
+                3                                                    // <2>
+            );
+        // end::span_first
+    }
+
+    public void testSpanMultiTerm() {
+        // tag::span_multi
+        spanMultiTermQueryBuilder(
+                prefixQuery("user", "ki"));                          // <1>
+        // end::span_multi
+    }
+
+    public void testSpanNear() {
+        // tag::span_near
+        spanNearQuery(
+                spanTermQuery("field","value1"),                     // <1>
+                12)                                                  // <2>
+                    .addClause(spanTermQuery("field","value2"))      // <1>
+                    .addClause(spanTermQuery("field","value3"))      // <1>
+                    .inOrder(false);                                 // <3>
+        // end::span_near
+    }
+
+    public void testSpanNot() {
+        // tag::span_not
+        spanNotQuery(
+                spanTermQuery("field","value1"),                     // <1>
+                spanTermQuery("field","value2"));                    // <2>
+        // end::span_not
+    }
+
+    public void testSpanOr() {
+        // tag::span_or
+        spanOrQuery(spanTermQuery("field","value1"))                 // <1>
+            .addClause(spanTermQuery("field","value2"))              // <1>
+            .addClause(spanTermQuery("field","value3"));             // <1>
+        // end::span_or
+    }
+
+    public void testSpanTerm() {
+        // tag::span_term
+        spanTermQuery(
+                "user",       // <1>
+                "kimchy");    // <2>
+        // end::span_term
+    }
+
+    public void testSpanWithin() {
+        // tag::span_within
+        spanWithinQuery(
+                spanNearQuery(spanTermQuery("field1", "bar"), 5)     // <1>
+                    .addClause(spanTermQuery("field1", "baz"))
+                    .inOrder(true),
+                spanTermQuery("field1", "foo"));                     // <2>
+        // end::span_within
+    }
+
+    public void testTerm() {
+        // tag::term
+        termQuery(
+                "name",                                              // <1>
+                "kimchy");                                           // <2>
+        // end::term
+    }
+
+    public void testTerms() {
+        // tag::terms
+        termsQuery("tags",                                           // <1>
+                "blue", "pill");                                     // <2>
+        // end::terms
+    }
+
+    public void testType() {
+        // tag::type
+        typeQuery("my_type");                                        // <1>
+        // end::type
+    }
+
+    public void testWildcard() {
+        // tag::wildcard
+        wildcardQuery(
+                "user",                                              // <1>
+                "k?mch*");                                           // <2>
+        // end::wildcard
+    }
+}

core/src/test/java/org/elasticsearch/index/query/QueryDSLDocumentationTests.java

@@ -1,341 +0,0 @@
-/*
- * Licensed to Elasticsearch under one or more contributor
- * license agreements. See the NOTICE file distributed with
- * this work for additional information regarding copyright
- * ownership. Elasticsearch licenses this file to you under
- * the Apache License, Version 2.0 (the "License"); you may
- * not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *    http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing,
- * software distributed under the License is distributed on an
- * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- * KIND, either express or implied.  See the License for the
- * specific language governing permissions and limitations
- * under the License.
- */
-
-package org.elasticsearch.index.query;
-
-import org.apache.lucene.search.join.ScoreMode;
-import org.elasticsearch.common.geo.GeoDistance;
-import org.elasticsearch.common.geo.GeoPoint;
-import org.elasticsearch.common.geo.ShapeRelation;
-import org.elasticsearch.common.geo.builders.CoordinatesBuilder;
-import org.elasticsearch.common.geo.builders.ShapeBuilders;
-import org.elasticsearch.common.unit.DistanceUnit;
-import org.elasticsearch.index.query.MoreLikeThisQueryBuilder.Item;
-import org.elasticsearch.index.query.functionscore.FunctionScoreQueryBuilder;
-import org.elasticsearch.index.query.functionscore.FunctionScoreQueryBuilder.FilterFunctionBuilder;
-import org.elasticsearch.script.Script;
-import org.elasticsearch.script.ScriptType;
-import org.elasticsearch.test.ESTestCase;
-
-import java.io.IOException;
-import java.util.ArrayList;
-import java.util.HashMap;
-import java.util.List;
-import java.util.Map;
-
-import static org.elasticsearch.index.query.QueryBuilders.boolQuery;
-import static org.elasticsearch.index.query.QueryBuilders.boostingQuery;
-import static org.elasticsearch.index.query.QueryBuilders.commonTermsQuery;
-import static org.elasticsearch.index.query.QueryBuilders.constantScoreQuery;
-import static org.elasticsearch.index.query.QueryBuilders.disMaxQuery;
-import static org.elasticsearch.index.query.QueryBuilders.existsQuery;
-import static org.elasticsearch.index.query.QueryBuilders.functionScoreQuery;
-import static org.elasticsearch.index.query.QueryBuilders.fuzzyQuery;
-import static org.elasticsearch.index.query.QueryBuilders.geoBoundingBoxQuery;
-import static org.elasticsearch.index.query.QueryBuilders.geoDistanceQuery;
-import static org.elasticsearch.index.query.QueryBuilders.geoPolygonQuery;
-import static org.elasticsearch.index.query.QueryBuilders.geoShapeQuery;
-import static org.elasticsearch.index.query.QueryBuilders.hasChildQuery;
-import static org.elasticsearch.index.query.QueryBuilders.hasParentQuery;
-import static org.elasticsearch.index.query.QueryBuilders.idsQuery;
-import static org.elasticsearch.index.query.QueryBuilders.matchAllQuery;
-import static org.elasticsearch.index.query.QueryBuilders.matchQuery;
-import static org.elasticsearch.index.query.QueryBuilders.moreLikeThisQuery;
-import static org.elasticsearch.index.query.QueryBuilders.multiMatchQuery;
-import static org.elasticsearch.index.query.QueryBuilders.nestedQuery;
-import static org.elasticsearch.index.query.QueryBuilders.prefixQuery;
-import static org.elasticsearch.index.query.QueryBuilders.queryStringQuery;
-import static org.elasticsearch.index.query.QueryBuilders.rangeQuery;
-import static org.elasticsearch.index.query.QueryBuilders.regexpQuery;
-import static org.elasticsearch.index.query.QueryBuilders.scriptQuery;
-import static org.elasticsearch.index.query.QueryBuilders.simpleQueryStringQuery;
-import static org.elasticsearch.index.query.QueryBuilders.spanContainingQuery;
-import static org.elasticsearch.index.query.QueryBuilders.spanFirstQuery;
-import static org.elasticsearch.index.query.QueryBuilders.spanMultiTermQueryBuilder;
-import static org.elasticsearch.index.query.QueryBuilders.spanNearQuery;
-import static org.elasticsearch.index.query.QueryBuilders.spanNotQuery;
-import static org.elasticsearch.index.query.QueryBuilders.spanOrQuery;
-import static org.elasticsearch.index.query.QueryBuilders.spanTermQuery;
-import static org.elasticsearch.index.query.QueryBuilders.spanWithinQuery;
-import static org.elasticsearch.index.query.QueryBuilders.termQuery;
-import static org.elasticsearch.index.query.QueryBuilders.termsQuery;
-import static org.elasticsearch.index.query.QueryBuilders.typeQuery;
-import static org.elasticsearch.index.query.QueryBuilders.wildcardQuery;
-import static org.elasticsearch.index.query.functionscore.ScoreFunctionBuilders.exponentialDecayFunction;
-import static org.elasticsearch.index.query.functionscore.ScoreFunctionBuilders.randomFunction;
-
-/**
- * If one of the following tests doesn't compile make sure to not only fix the compilation error here
- * but also the documentation under ./docs/java-api/query-dsl/bool-query.asciidoc
- *
- * There are no assertions here on purpose - all of these tests ((ideally) should) equal to what is
- * documented in the java api query dsl part of our reference guide.
- * */
-public class QueryDSLDocumentationTests extends ESTestCase {
-    public void testBool() {
-        boolQuery()
-                .must(termQuery("content", "test1"))
-                .must(termQuery("content", "test4"))
-                .mustNot(termQuery("content", "test2"))
-                .should(termQuery("content", "test3"))
-                .filter(termQuery("content", "test5"));
-    }
-
-    public void testBoosting() {
-        boostingQuery(termQuery("name","kimchy"), termQuery("name","dadoonet"))
-                .negativeBoost(0.2f);
-    }
-
-    public void testCommonTerms() {
-        commonTermsQuery("name", "kimchy");
-    }
-
-    public void testConstantScore() {
-        constantScoreQuery(termQuery("name","kimchy"))
-            .boost(2.0f);
-    }
-
-    public void testDisMax() {
-        disMaxQuery()
-                .add(termQuery("name", "kimchy"))
-                .add(termQuery("name", "elasticsearch"))
-                .boost(1.2f)
-                .tieBreaker(0.7f);
-    }
-
-    public void testExists() {
-        existsQuery("name");
-    }
-
-    public void testFunctionScore() {
-        FilterFunctionBuilder[] functions = {
-                new FunctionScoreQueryBuilder.FilterFunctionBuilder(
-                        matchQuery("name", "kimchy"),
-                        randomFunction("ABCDEF")),
-                new FunctionScoreQueryBuilder.FilterFunctionBuilder(
-                        exponentialDecayFunction("age", 0L, 1L))
-        };
-        functionScoreQuery(functions);
-    }
-
-    public void testFuzzy() {
-        fuzzyQuery("name", "kimchy");
-    }
-
-    public void testGeoBoundingBox() {
-        geoBoundingBoxQuery("pin.location").setCorners(40.73, -74.1, 40.717, -73.99);
-    }
-
-    public void testGeoDistance() {
-        geoDistanceQuery("pin.location")
-            .point(40, -70)
-            .distance(200, DistanceUnit.KILOMETERS)
-            .geoDistance(GeoDistance.ARC);
-    }
-
-    public void testGeoPolygon() {
-        List<GeoPoint> points = new ArrayList<GeoPoint>();
-        points.add(new GeoPoint(40, -70));
-        points.add(new GeoPoint(30, -80));
-        points.add(new GeoPoint(20, -90));
-        geoPolygonQuery("pin.location", points);
-    }
-
-    public void testGeoShape() throws IOException {
-        GeoShapeQueryBuilder qb = geoShapeQuery(
-                "pin.location",
-                ShapeBuilders.newMultiPoint(
-                        new CoordinatesBuilder()
-                    .coordinate(0, 0)
-                    .coordinate(0, 10)
-                    .coordinate(10, 10)
-                    .coordinate(10, 0)
-                    .coordinate(0, 0)
-                    .build()));
-        qb.relation(ShapeRelation.WITHIN);
-
-        qb = geoShapeQuery(
-                    "pin.location",
-                    "DEU",
-                    "countries");
-        qb.relation(ShapeRelation.WITHIN)
-            .indexedShapeIndex("shapes")
-            .indexedShapePath("location");
-    }
-
-    public void testHasChild() {
-        hasChildQuery(
-                "blog_tag",
-                termQuery("tag","something"),
-                ScoreMode.None);
-    }
-
-    public void testHasParent() {
-        hasParentQuery(
-            "blog",
-            termQuery("tag","something"),
-                false);
-    }
-
-    public void testIds() {
-        idsQuery("my_type", "type2")
-                .addIds("1", "4", "100");
-
-        idsQuery().addIds("1", "4", "100");
-    }
-
-    public void testMatchAll() {
-        matchAllQuery();
-    }
-
-    public void testMatch() {
-        matchQuery("name", "kimchy elasticsearch");
-    }
-
-    public void testMLT() {
-        String[] fields = {"name.first", "name.last"};
-        String[] texts = {"text like this one"};
-        Item[] items = null;
-
-        moreLikeThisQuery(fields, texts, items)
-        .minTermFreq(1)
-        .maxQueryTerms(12);
-    }
-
-    public void testMultiMatch() {
-        multiMatchQuery("kimchy elasticsearch", "user", "message");
-    }
-
-    public void testNested() {
-        nestedQuery(
-                "obj1",
-                boolQuery()
-                        .must(matchQuery("obj1.name", "blue"))
-                        .must(rangeQuery("obj1.count").gt(5)),
-                ScoreMode.Avg);
-    }
-
-    public void testPrefix() {
-        prefixQuery("brand", "heine");
-    }
-
-    public void testQueryString() {
-        queryStringQuery("+kimchy -elasticsearch");
-    }
-
-    public void testRange() {
-        rangeQuery("price")
-        .from(5)
-        .to(10)
-        .includeLower(true)
-        .includeUpper(false);
-
-        rangeQuery("age")
-        .gte("10")
-        .lt("20");
-    }
-
-    public void testRegExp() {
-        regexpQuery("name.first", "s.*y");
-    }
-
-    public void testScript() {
-        scriptQuery(
-                new Script("doc['num1'].value > 1")
-            );
-
-        Map<String, Object> parameters = new HashMap<>();
-        parameters.put("param1", 5);
-        scriptQuery(
-                new Script(
-                    ScriptType.FILE, "coollang", "myscript",
-                    parameters)
-            );
-
-    }
-
-    public void testSimpleQueryString() {
-        simpleQueryStringQuery("+kimchy -elasticsearch");
-    }
-
-    public void testSpanContaining() {
-        spanContainingQuery(
-                spanNearQuery(spanTermQuery("field1","bar"), 5)
-                    .addClause(spanTermQuery("field1","baz"))
-                    .inOrder(true),
-                spanTermQuery("field1","foo"));
-    }
-
-    public void testSpanFirst() {
-        spanFirstQuery(
-                spanTermQuery("user", "kimchy"),
-                3
-            );
-    }
-
-    public void testSpanMultiTerm() {
-        spanMultiTermQueryBuilder(prefixQuery("user", "ki"));
-    }
-
-    public void testSpanNear() {
-        spanNearQuery(spanTermQuery("field","value1"), 12)
-        .addClause(spanTermQuery("field","value2"))
-        .addClause(spanTermQuery("field","value3"))
-        .inOrder(false);
-    }
-
-    public void testSpanNot() {
-        spanNotQuery(spanTermQuery("field","value1"),
-                spanTermQuery("field","value2"));
-    }
-
-    public void testSpanOr() {
-        spanOrQuery(spanTermQuery("field","value1"))
-        .addClause(spanTermQuery("field","value2"))
-        .addClause(spanTermQuery("field","value3"));
-    }
-
-    public void testSpanTerm() {
-        spanTermQuery("user", "kimchy");
-    }
-
-    public void testSpanWithin() {
-        spanWithinQuery(
-                spanNearQuery(spanTermQuery("field1", "bar"), 5)
-                    .addClause(spanTermQuery("field1", "baz"))
-                    .inOrder(true),
-                spanTermQuery("field1", "foo"));
-    }
-
-    public void testTerm() {
-        termQuery("name", "kimchy");
-    }
-
-    public void testTerms() {
-        termsQuery("tags", "blue", "pill");
-    }
-
-    public void testType() {
-        typeQuery("my_type");
-    }
-
-    public void testWildcard() {
-        wildcardQuery("user", "k?mch*");
-    }
-}

docs/java-api/query-dsl.asciidoc

@@ -19,6 +19,8 @@ Note that you can easily print (aka debug) JSON generated queries using
 The `QueryBuilder` can then be used with any API that accepts a query,
 such as `count` and `search`.
 
+:query-dsl-test: {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java
+
 include::query-dsl/match-all-query.asciidoc[]
 
 include::query-dsl/full-text-queries.asciidoc[]
@@ -35,4 +37,4 @@ include::query-dsl/special-queries.asciidoc[]
 
 include::query-dsl/span-queries.asciidoc[]
 
-
+:query-dsl-test!:

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

@@ -3,17 +3,11 @@
 
 See {ref}/query-dsl-bool-query.html[Bool Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = boolQuery()
-    .must(termQuery("content", "test1"))    <1>
-    .must(termQuery("content", "test4"))    <1>
-    .mustNot(termQuery("content", "test2")) <2>
-    .should(termQuery("content", "test3"))  <3>
-    .filter(termQuery("content", "test5")); <4>
+include-tagged::{query-dsl-test}[bool]
 --------------------------------------------------
 <1> must query
 <2> must not query
 <3> should query
 <4> a query that must appear in the matching documents but doesn't contribute to scoring.
-

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

@@ -3,14 +3,10 @@
 
 See {ref}/query-dsl-boosting-query.html[Boosting Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = boostingQuery(
-        termQuery("name","kimchy"),    <1> 
-        termQuery("name","dadoonet"))  <2>
-    .negativeBoost(0.2f);              <3>
+include-tagged::{query-dsl-test}[boosting]
 --------------------------------------------------
 <1> query that will promote documents
 <2> query that will demote documents
 <3> negative boost
-

docs/java-api/query-dsl/common-terms-query.asciidoc

@@ -3,10 +3,9 @@
 
 See {ref}/query-dsl-common-terms-query.html[Common Terms Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = commonTermsQuery("name",    <1>
-                                   "kimchy"); <2>
+include-tagged::{query-dsl-test}[common_terms]
 --------------------------------------------------
 <1> field
 <2> value

docs/java-api/query-dsl/constant-score-query.asciidoc

@@ -3,12 +3,9 @@
 
 See {ref}/query-dsl-constant-score-query.html[Constant Score Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = constantScoreQuery(
-        termQuery("name","kimchy")      <1>
-    )
-    .boost(2.0f);                       <2>
+include-tagged::{query-dsl-test}[constant_score]
 --------------------------------------------------
 <1> your query
 <2> query score

docs/java-api/query-dsl/dis-max-query.asciidoc

@@ -3,13 +3,9 @@
 
 See {ref}/query-dsl-dis-max-query.html[Dis Max Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = disMaxQuery()
-    .add(termQuery("name", "kimchy"))        <1>
-    .add(termQuery("name", "elasticsearch")) <2>
-    .boost(1.2f)                             <3>
-    .tieBreaker(0.7f);                       <4>
+include-tagged::{query-dsl-test}[dis_max]
 --------------------------------------------------
 <1> add your queries
 <2> add your queries

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

@@ -3,9 +3,8 @@
 
 See {ref}/query-dsl-exists-query.html[Exists Query].
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = existsQuery("name");       <1>
+include-tagged::{query-dsl-test}[exists]
 --------------------------------------------------
 <1> field
-

docs/java-api/query-dsl/function-score-query.asciidoc

@@ -10,18 +10,10 @@ To use `ScoreFunctionBuilders` just import them in your class:
 import static org.elasticsearch.index.query.functionscore.ScoreFunctionBuilders.*;
 --------------------------------------------------
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-FilterFunctionBuilder[] functions = {
-        new FunctionScoreQueryBuilder.FilterFunctionBuilder(
-                matchQuery("name", "kimchy"),                 <1>
-                randomFunction("ABCDEF")),                    <2>
-        new FunctionScoreQueryBuilder.FilterFunctionBuilder(
-                exponentialDecayFunction("age", 0L, 1L))      <3>
-};
-QueryBuilder qb = QueryBuilders.functionScoreQuery(functions);
+include-tagged::{query-dsl-test}[function_score]
 --------------------------------------------------
 <1> Add a first function based on a query
 <2> And randomize the score based on a given seed
 <3> Add another function based on the age field
-

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

@@ -3,13 +3,9 @@
 
 See {ref}/query-dsl-fuzzy-query.html[Fuzzy Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = fuzzyQuery(
-    "name",     <1>
-    "kimzhy"    <2>
-);
+include-tagged::{query-dsl-test}[fuzzy]
 --------------------------------------------------
 <1> field
 <2> text
-

docs/java-api/query-dsl/geo-bounding-box-query.asciidoc

@@ -3,14 +3,10 @@
 
 See {ref}/query-dsl-geo-bounding-box-query.html[Geo Bounding Box Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = geoBoundingBoxQuery("pin.location") <1>
-    .setCorners(40.73, -74.1,                         <2>
-                40.717, -73.99);                      <3>
+include-tagged::{query-dsl-test}[geo_bounding_box]
 --------------------------------------------------
 <1> field
 <2> bounding box top left point
 <3> bounding box bottom right point
-
-

docs/java-api/query-dsl/geo-distance-query.asciidoc

@@ -3,13 +3,10 @@
 
 See {ref}/query-dsl-geo-distance-query.html[Geo Distance Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = geoDistanceQuery("pin.location")  <1>
-    .point(40, -70)                                 <2>
-    .distance(200, DistanceUnit.KILOMETERS);        <3>
+include-tagged::{query-dsl-test}[geo_bounding_box]
 --------------------------------------------------
 <1> field
 <2> center point
 <3> distance from center point
-

docs/java-api/query-dsl/geo-polygon-query.asciidoc

@@ -3,16 +3,9 @@
 
 See {ref}/query-dsl-geo-polygon-query.html[Geo Polygon Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-List<GeoPoint> points = new ArrayList<>();             <1>
-points.add(new GeoPoint(40, -70));
-points.add(new GeoPoint(30, -80));
-points.add(new GeoPoint(20, -90));
-
-QueryBuilder qb = 
-        geoPolygonQuery("pin.location", points);       <2>
+include-tagged::{query-dsl-test}[geo_polygon]
 --------------------------------------------------
 <1> add your polygon of points a document should fall within
 <2> initialise the query with field and points
-

docs/java-api/query-dsl/geo-shape-query.asciidoc

@@ -37,34 +37,17 @@ import org.elasticsearch.common.geo.ShapeRelation;
 import org.elasticsearch.common.geo.builders.ShapeBuilder;
 --------------------------------------------------
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-List<Coordinate> points = new ArrayList<>();
-points.add(new Coordinate(0, 0));
-points.add(new Coordinate(0, 10));
-points.add(new Coordinate(10, 10));
-points.add(new Coordinate(10, 0));
-points.add(new Coordinate(0, 0));
-
-QueryBuilder qb = geoShapeQuery(
-        "pin.location",                         <1>
-        ShapeBuilders.newMultiPoint(points)     <2>
-        .relation(ShapeRelation.WITHIN);        <3>
+include-tagged::{query-dsl-test}[geo_shape]
 --------------------------------------------------
 <1> field
 <2> shape
 <3> relation can be `ShapeRelation.CONTAINS`, `ShapeRelation.WITHIN`, `ShapeRelation.INTERSECTS` or `ShapeRelation.DISJOINT`
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-// Using pre-indexed shapes
-QueryBuilder qb = geoShapeQuery(
-        "pin.location",                  <1>
-        "DEU",                           <2>
-        "countries")                     <3>
-        .relation(ShapeRelation.WITHIN)) <4>
-        .indexedShapeIndex("shapes")     <5>
-        .indexedShapePath("location");   <6>
+include-tagged::{query-dsl-test}[indexed_geo_shape]
 --------------------------------------------------
 <1> field
 <2> The ID of the document that containing the pre-indexed shape.

docs/java-api/query-dsl/has-child-query.asciidoc

@@ -3,15 +3,10 @@
 
 See {ref}/query-dsl-has-child-query.html[Has Child Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = hasChildQuery(
-    "blog_tag",                     <1>
-    termQuery("tag","something"),   <2>
-    ScoreMode.Avg                   <3>
-);
+include-tagged::{query-dsl-test}[has_child]
 --------------------------------------------------
 <1> child type to query against
 <2> query
 <3> score mode can be `ScoreMode.Avg`, `ScoreMode.Max`, `ScoreMode.Min`, `ScoreMode.None` or `ScoreMode.Total`
-

docs/java-api/query-dsl/has-parent-query.asciidoc

@@ -3,14 +3,10 @@
 
 See {ref}/query-dsl-has-parent-query.html[Has Parent]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = hasParentQuery(
-    "blog",                         <1>
-    termQuery("tag","something"),   <2>
-    false                           <3>
-);
+include-tagged::{query-dsl-test}[has_parent]
 --------------------------------------------------
 <1> parent type to query against
 <2> query
-<3> whether the score from the parent hit should propogate to the child hit
+<3> whether the score from the parent hit should propagate to the child hit

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

@@ -4,13 +4,8 @@
 
 See {ref}/query-dsl-ids-query.html[Ids Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = idsQuery("my_type", "type2")
-    .addIds("1", "4", "100");
-
-QueryBuilder qb = idsQuery() <1>
-    .addIds("1", "4", "100");
+include-tagged::{query-dsl-test}[ids]
 --------------------------------------------------
 <1> type is optional
-

docs/java-api/query-dsl/match-all-query.asciidoc

@@ -3,7 +3,7 @@
 
 See {ref}/query-dsl-match-all-query.html[Match All Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = matchAllQuery();
+include-tagged::{query-dsl-test}[match_all]
 --------------------------------------------------

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

@@ -3,13 +3,9 @@
 
 See {ref}/query-dsl-match-query.html[Match Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = matchQuery(
-    "name",                  <1>
-    "kimchy elasticsearch"   <2>
-);
+include-tagged::{query-dsl-test}[match]
 --------------------------------------------------
 <1> field
 <2> text
-

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

@@ -1,18 +1,11 @@
 [[java-query-dsl-mlt-query]]
 ==== More Like This Query
 
-See:
- * {ref}/query-dsl-mlt-query.html[More Like This Query]
+See {ref}/query-dsl-mlt-query.html[More Like This Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-String[] fields = {"name.first", "name.last"};                 <1>
-String[] texts = {"text like this one"};                       <2>
-Item[] items = null;
-                                
-QueryBuilder qb = moreLikeThisQuery(fields, texts, items)
-    .minTermFreq(1)                                            <3>
-    .maxQueryTerms(12);                                        <4>
+include-tagged::{query-dsl-test}[more_like_this]
 --------------------------------------------------
 <1> fields
 <2> text

docs/java-api/query-dsl/multi-match-query.asciidoc

@@ -3,12 +3,9 @@
 
 See {ref}/query-dsl-multi-match-query.html[Multi Match Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = multiMatchQuery(
-    "kimchy elasticsearch", <1>
-    "user", "message"       <2>
-);
+include-tagged::{query-dsl-test}[multi_match]
 --------------------------------------------------
 <1> text
 <2> fields

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

@@ -3,15 +3,9 @@
 
 See {ref}/query-dsl-nested-query.html[Nested Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = nestedQuery(
-        "obj1",                       <1>
-        boolQuery()                   <2>
-                .must(matchQuery("obj1.name", "blue"))
-                .must(rangeQuery("obj1.count").gt(5)),
-        ScoreMode.Avg                 <3>
-    );
+include-tagged::{query-dsl-test}[nested]
 --------------------------------------------------
 <1> path to nested document
 <2> your query. Any fields referenced inside the query must use the complete path (fully qualified).

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

@@ -3,14 +3,9 @@
 
 See {ref}/query-dsl-prefix-query.html[Prefix Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = prefixQuery(
-    "brand",    <1>
-    "heine"     <2>
-);
+include-tagged::{query-dsl-test}[prefix]
 --------------------------------------------------
 <1> field
 <2> prefix
-
-

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

@@ -3,8 +3,7 @@
 
 See {ref}/query-dsl-query-string-query.html[Query String Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = queryStringQuery("+kimchy -elasticsearch");    <1>
+include-tagged::{query-dsl-test}[query_string]
 --------------------------------------------------
-<1> text

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

@@ -3,13 +3,9 @@
 
 See {ref}/query-dsl-range-query.html[Range Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = rangeQuery("price")   <1>
-    .from(5)                            <2>
-    .to(10)                             <3>
-    .includeLower(true)                 <4>
-    .includeUpper(false);               <5>
+include-tagged::{query-dsl-test}[range]
 --------------------------------------------------
 <1> field
 <2> from
@@ -17,12 +13,9 @@ QueryBuilder qb = rangeQuery("price")   <1>
 <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]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-// A simplified form using gte, gt, lt or lte
-QueryBuilder qb = rangeQuery("age")   <1>
-    .gte("10")                        <2>
-    .lt("20");                        <3>
+include-tagged::{query-dsl-test}[range_simplified]
 --------------------------------------------------
 <1> field
 <2> set `from` to 10 and `includeLower` to `true`

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

@@ -3,11 +3,9 @@
 
 See {ref}/query-dsl-regexp-query.html[Regexp Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = regexpQuery(
-    "name.first",        <1>
-    "s.*y");             <2>
+include-tagged::{query-dsl-test}[regexp]
 --------------------------------------------------
 <1> field
 <2> regexp

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

@@ -3,11 +3,9 @@
 
 See {ref}/query-dsl-script-query.html[Script Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = scriptQuery(
-    new Script("doc['num1'].value > 1") <1>
-);
+include-tagged::{query-dsl-test}[script_inline]
 --------------------------------------------------
 <1> inlined script
 
@@ -21,17 +19,11 @@ doc['num1'].value > params.param1
 
 You can use it then with:
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = scriptQuery(
-    new Script(
-        ScriptType.FILE,                       <1>
-        "painless",                            <2>
-        "myscript",                            <3>
-        Collections.singletonMap("param1", 5)) <4>
-);
+include-tagged::{query-dsl-test}[script_file]
 --------------------------------------------------
 <1> Script type: either `ScriptType.FILE`, `ScriptType.INLINE` or `ScriptType.INDEXED`
 <2> Scripting engine
 <3> Script name
-<4> Parameters as a `Map` of `<String, Object>`
+<4> Parameters as a `Map<String, Object>`

docs/java-api/query-dsl/simple-query-string-query.asciidoc

@@ -3,8 +3,7 @@
 
 See {ref}/query-dsl-simple-query-string-query.html[Simple Query String Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = simpleQueryStringQuery("+kimchy -elasticsearch");    <1>
+include-tagged::{query-dsl-test}[simple_query_string]
 --------------------------------------------------
-<1> text

docs/java-api/query-dsl/span-containing-query.asciidoc

@@ -3,14 +3,9 @@
 
 See {ref}/query-dsl-span-containing-query.html[Span Containing Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = spanContainingQuery(
-    spanNearQuery(spanTermQuery("field1","bar"), 5) <1>
-          .addClause(spanTermQuery("field1","baz"))
-          .inOrder(true),
-    spanTermQuery("field1","foo"));                 <2>
+include-tagged::{query-dsl-test}[span_containing]
 --------------------------------------------------
 <1> `big` part
 <2> `little` part
-

docs/java-api/query-dsl/span-first-query.asciidoc

@@ -3,13 +3,9 @@
 
 See {ref}/query-dsl-span-first-query.html[Span First Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = spanFirstQuery(
-    spanTermQuery("user", "kimchy"),            <1>
-    3                                           <2>
-);
+include-tagged::{query-dsl-test}[span_first]
 --------------------------------------------------
 <1> query
 <2> max end position
-

docs/java-api/query-dsl/span-multi-term-query.asciidoc

@@ -3,12 +3,9 @@
 
 See {ref}/query-dsl-span-multi-term-query.html[Span Multi Term Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = spanMultiTermQueryBuilder(
-    prefixQuery("user", "ki")                   <1>
-);
+include-tagged::{query-dsl-test}[span_multi]
 --------------------------------------------------
 <1> Can be any builder extending the `MultiTermQueryBuilder` class. For example: `FuzzyQueryBuilder`,
 `PrefixQueryBuilder`, `RangeQueryBuilder`, `RegexpQueryBuilder` or `WildcardQueryBuilder`.
-

docs/java-api/query-dsl/span-near-query.asciidoc

@@ -3,16 +3,10 @@
 
 See {ref}/query-dsl-span-near-query.html[Span Near Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = spanNearQuery(
-    spanTermQuery("field","value1"),            <1>
-    12)                                         <2>
-    .addClause(spanTermQuery("field","value2")) <1>
-    .addClause(spanTermQuery("field","value3")) <1>
-    .inOrder(false);                            <3>
+include-tagged::{query-dsl-test}[span_near]
 --------------------------------------------------
 <1> span term queries
 <2> slop factor: the maximum number of intervening unmatched positions
 <3> whether matches are required to be in-order
-

docs/java-api/query-dsl/span-not-query.asciidoc

@@ -3,12 +3,9 @@
 
 See {ref}/query-dsl-span-not-query.html[Span Not Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = spanNotQuery(
-    spanTermQuery("field","value1"),   <1>
-    spanTermQuery("field","value2"));  <2>
+include-tagged::{query-dsl-test}[span_not]
 --------------------------------------------------
 <1> span query whose matches are filtered
 <2> span query whose matches must not overlap those returned
-

docs/java-api/query-dsl/span-or-query.asciidoc

@@ -3,12 +3,8 @@
 
 See {ref}/query-dsl-span-or-query.html[Span Or Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = spanOrQuery(
-    spanTermQuery("field","value1"))               <1>
-    .addClause(spanTermQuery("field","value2"))    <1>
-    .addClause(spanTermQuery("field","value3"));   <1>
+include-tagged::{query-dsl-test}[span_or]
 --------------------------------------------------
 <1> span term queries
-

docs/java-api/query-dsl/span-term-query.asciidoc

@@ -3,13 +3,9 @@
 
 See {ref}/query-dsl-span-term-query.html[Span Term Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = spanTermQuery(
-    "user",                                     <1>
-    "kimchy"                                    <2>
-);
+include-tagged::{query-dsl-test}[span_term]
 --------------------------------------------------
 <1> field
 <2> value
-

docs/java-api/query-dsl/span-within-query.asciidoc

@@ -3,13 +3,9 @@
 
 See {ref}/query-dsl-span-within-query.html[Span Within Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = spanWithinQuery(
-    spanNearQuery(spanTermQuery("field1", "bar"), 5) <1>
-        .addClause(spanTermQuery("field1", "baz"))
-        .inOrder(true),
-    spanTermQuery("field1", "foo"));                 <2>
+include-tagged::{query-dsl-test}[span_within]
 --------------------------------------------------
 <1> `big` part
 <2> `little` part

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

@@ -3,13 +3,9 @@
 
 See {ref}/query-dsl-term-query.html[Term Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = termQuery(
-    "name",    <1>
-    "kimchy"   <2>
-);
+include-tagged::{query-dsl-test}[term]
 --------------------------------------------------
 <1> field
 <2> text
-

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

@@ -3,10 +3,9 @@
 
 See {ref}/query-dsl-terms-query.html[Terms Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = termsQuery("tags",    <1>
-    "blue", "pill");                    <2>
+include-tagged::{query-dsl-test}[terms]
 --------------------------------------------------
 <1> field
 <2> values

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

@@ -3,8 +3,8 @@
 
 See {ref}/query-dsl-type-query.html[Type Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = typeQuery("my_type"); <1>
+include-tagged::{query-dsl-test}[type]
 --------------------------------------------------
 <1> type

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

@@ -3,8 +3,9 @@
 
 See {ref}/query-dsl-wildcard-query.html[Wildcard Query]
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-QueryBuilder qb = wildcardQuery("user", "k?mc*");
+include-tagged::{query-dsl-test}[wildcard]
 --------------------------------------------------
-
+<1> field
+<2> wildcard expression