From c5821f9645bb02765b16ad26cd1d789982394f53 Mon Sep 17 00:00:00 2001 From: olcbean <26058559+olcbean@users.noreply.github.com> Date: Mon, 26 Feb 2018 20:03:03 +0100 Subject: [PATCH] [docs] Line breaks for High-level REST Client (#28825) Wrap code snippets for better display in the generated docs. --- .../documentation/CRUDDocumentationIT.java | 47 +++++++++++++------ .../ClusterClientDocumentationIT.java | 8 +++- .../IndicesClientDocumentationIT.java | 35 +++++++++----- .../documentation/SearchDocumentationIT.java | 29 ++++++++---- 4 files changed, 81 insertions(+), 38 deletions(-) diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java index 08d182f6eb9..16fa4f8d69c 100644 --- a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java +++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java @@ -74,8 +74,8 @@ import static java.util.Collections.singletonMap; /** * This class is used to generate the Java CRUD API documentation. * You need to wrap your code between two tags like: - * // tag::example[] - * // end::example[] + * // tag::example + * // end::example * * Where example is your tag name. * @@ -84,6 +84,10 @@ import static java.util.Collections.singletonMap; * -------------------------------------------------- * include-tagged::{doc-tests}/CRUDDocumentationIT.java[example] * -------------------------------------------------- + * + * The column width of the code block is 84. If the code contains a line longer + * than 84, the line will be cut and a horizontal scroll bar will be displayed. + * (the code indentation of the tag is not included in the width) */ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { @@ -284,7 +288,8 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { //tag::update-request-with-inline-script Map parameters = singletonMap("count", 4); // <1> - Script inline = new Script(ScriptType.INLINE, "painless", "ctx._source.field += params.count", parameters); // <2> + Script inline = new Script(ScriptType.INLINE, "painless", + "ctx._source.field += params.count", parameters); // <2> request.script(inline); // <3> //end::update-request-with-inline-script UpdateResponse updateResponse = client.update(request); @@ -393,7 +398,8 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { } { //tag::update-docnotfound - UpdateRequest request = new UpdateRequest("posts", "type", "does_not_exist").doc("field", "value"); + UpdateRequest request = new UpdateRequest("posts", "type", "does_not_exist") + .doc("field", "value"); try { UpdateResponse updateResponse = client.update(request); } catch (ElasticsearchException e) { @@ -813,7 +819,8 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { //tag::get-request-source-include String[] includes = new String[]{"message", "*Date"}; String[] excludes = Strings.EMPTY_ARRAY; - FetchSourceContext fetchSourceContext = new FetchSourceContext(true, includes, excludes); + FetchSourceContext fetchSourceContext = + new FetchSourceContext(true, includes, excludes); request.fetchSourceContext(fetchSourceContext); // <1> //end::get-request-source-include GetResponse getResponse = client.get(request); @@ -827,7 +834,8 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { //tag::get-request-source-exclude String[] includes = Strings.EMPTY_ARRAY; String[] excludes = new String[]{"message"}; - FetchSourceContext fetchSourceContext = new FetchSourceContext(true, includes, excludes); + FetchSourceContext fetchSourceContext = + new FetchSourceContext(true, includes, excludes); request.fetchSourceContext(fetchSourceContext); // <1> //end::get-request-source-exclude GetResponse getResponse = client.get(request); @@ -935,7 +943,8 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { } @Override - public void afterBulk(long executionId, BulkRequest request, BulkResponse response) { + public void afterBulk(long executionId, BulkRequest request, + BulkResponse response) { // <3> } @@ -945,17 +954,21 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { } }; - BulkProcessor bulkProcessor = BulkProcessor.builder(client::bulkAsync, listener).build(); // <5> + BulkProcessor bulkProcessor = + BulkProcessor.builder(client::bulkAsync, listener).build(); // <5> // end::bulk-processor-init assertNotNull(bulkProcessor); // tag::bulk-processor-add IndexRequest one = new IndexRequest("posts", "doc", "1"). - source(XContentType.JSON, "title", "In which order are my Elasticsearch queries executed?"); + source(XContentType.JSON, "title", + "In which order are my Elasticsearch queries executed?"); IndexRequest two = new IndexRequest("posts", "doc", "2") - .source(XContentType.JSON, "title", "Current status and upcoming changes in Elasticsearch"); + .source(XContentType.JSON, "title", + "Current status and upcoming changes in Elasticsearch"); IndexRequest three = new IndexRequest("posts", "doc", "3") - .source(XContentType.JSON, "title", "The Future of Federated Search in Elasticsearch"); + .source(XContentType.JSON, "title", + "The Future of Federated Search in Elasticsearch"); bulkProcessor.add(one); bulkProcessor.add(two); @@ -977,15 +990,18 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { @Override public void beforeBulk(long executionId, BulkRequest request) { int numberOfActions = request.numberOfActions(); // <1> - logger.debug("Executing bulk [{}] with {} requests", executionId, numberOfActions); + logger.debug("Executing bulk [{}] with {} requests", + executionId, numberOfActions); } @Override - public void afterBulk(long executionId, BulkRequest request, BulkResponse response) { + public void afterBulk(long executionId, BulkRequest request, + BulkResponse response) { if (response.hasFailures()) { // <2> logger.warn("Bulk [{}] executed with failures", executionId); } else { - logger.debug("Bulk [{}] completed in {} milliseconds", executionId, response.getTook().getMillis()); + logger.debug("Bulk [{}] completed in {} milliseconds", + executionId, response.getTook().getMillis()); } } @@ -1002,7 +1018,8 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { builder.setBulkSize(new ByteSizeValue(1L, ByteSizeUnit.MB)); // <2> builder.setConcurrentRequests(0); // <3> builder.setFlushInterval(TimeValue.timeValueSeconds(10L)); // <4> - builder.setBackoffPolicy(BackoffPolicy.constantBackoff(TimeValue.timeValueSeconds(1L), 3)); // <5> + builder.setBackoffPolicy(BackoffPolicy + .constantBackoff(TimeValue.timeValueSeconds(1L), 3)); // <5> // end::bulk-processor-options } } diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java index e9fc4ec01ba..0747ca757c4 100644 --- a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java +++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java @@ -43,8 +43,8 @@ import static org.hamcrest.Matchers.equalTo; /** * This class is used to generate the Java Cluster API documentation. * You need to wrap your code between two tags like: - * // tag::example[] - * // end::example[] + * // tag::example + * // end::example * * Where example is your tag name. * @@ -53,6 +53,10 @@ import static org.hamcrest.Matchers.equalTo; * -------------------------------------------------- * include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[example] * -------------------------------------------------- + * + * The column width of the code block is 84. If the code contains a line longer + * than 84, the line will be cut and a horizontal scroll bar will be displayed. + * (the code indentation of the tag is not included in the width) */ public class ClusterClientDocumentationIT extends ESRestHighLevelClientTestCase { diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java index 843c5c42fff..06b97eb716e 100644 --- a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java +++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java @@ -66,8 +66,8 @@ import java.util.concurrent.TimeUnit; /** * This class is used to generate the Java Indices API documentation. * You need to wrap your code between two tags like: - * // tag::example[] - * // end::example[] + * // tag::example + * // end::example * * Where example is your tag name. * @@ -76,6 +76,10 @@ import java.util.concurrent.TimeUnit; * -------------------------------------------------- * include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[example] * -------------------------------------------------- + * + * The column width of the code block is 84. If the code contains a line longer + * than 84, the line will be cut and a horizontal scroll bar will be displayed. + * (the code indentation of the tag is not included in the width) */ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase { @@ -207,7 +211,8 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase DeleteIndexRequest request = new DeleteIndexRequest("posts"); // tag::delete-index-execute-listener - ActionListener listener = new ActionListener() { + ActionListener listener = + new ActionListener() { @Override public void onResponse(DeleteIndexResponse deleteIndexResponse) { // <1> @@ -378,7 +383,8 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase CreateIndexRequest request = new CreateIndexRequest("twitter"); // tag::create-index-execute-listener - ActionListener listener = new ActionListener() { + ActionListener listener = + new ActionListener() { @Override public void onResponse(CreateIndexResponse createIndexResponse) { // <1> @@ -507,7 +513,8 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase PutMappingRequest request = new PutMappingRequest("twitter").type("tweet"); // tag::put-mapping-execute-listener - ActionListener listener = new ActionListener() { + ActionListener listener = + new ActionListener() { @Override public void onResponse(PutMappingResponse putMappingResponse) { // <1> @@ -574,7 +581,8 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase assertTrue(shardsAcked); // tag::open-index-execute-listener - ActionListener listener = new ActionListener() { + ActionListener listener = + new ActionListener() { @Override public void onResponse(OpenIndexResponse openIndexResponse) { // <1> @@ -648,7 +656,8 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase assertTrue(acknowledged); // tag::close-index-execute-listener - ActionListener listener = new ActionListener() { + ActionListener listener = + new ActionListener() { @Override public void onResponse(CloseIndexResponse closeIndexResponse) { // <1> @@ -686,7 +695,8 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase // tag::exists-alias-request GetAliasesRequest request = new GetAliasesRequest(); GetAliasesRequest requestWithAlias = new GetAliasesRequest("alias1"); - GetAliasesRequest requestWithAliases = new GetAliasesRequest(new String[]{"alias1", "alias2"}); + GetAliasesRequest requestWithAliases = + new GetAliasesRequest(new String[]{"alias1", "alias2"}); // end::exists-alias-request // tag::exists-alias-request-alias @@ -860,7 +870,8 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase request.setWaitForActiveShards(ActiveShardCount.DEFAULT); // <2> // end::shrink-index-request-waitForActiveShards // tag::shrink-index-request-settings - request.getTargetIndexRequest().settings(Settings.builder().put("index.number_of_shards", 2)); // <1> + request.getTargetIndexRequest().settings(Settings.builder() + .put("index.number_of_shards", 2)); // <1> // end::shrink-index-request-settings // tag::shrink-index-request-aliases request.getTargetIndexRequest().alias(new Alias("target_alias")); // <1> @@ -929,7 +940,8 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase request.setWaitForActiveShards(ActiveShardCount.DEFAULT); // <2> // end::split-index-request-waitForActiveShards // tag::split-index-request-settings - request.getTargetIndexRequest().settings(Settings.builder().put("index.number_of_shards", 4)); // <1> + request.getTargetIndexRequest().settings(Settings.builder() + .put("index.number_of_shards", 4)); // <1> // end::split-index-request-settings // tag::split-index-request-aliases request.getTargetIndexRequest().alias(new Alias("target_alias")); // <1> @@ -1001,7 +1013,8 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase request.getCreateIndexRequest().waitForActiveShards(ActiveShardCount.DEFAULT); // <2> // end::rollover-request-waitForActiveShards // tag::rollover-request-settings - request.getCreateIndexRequest().settings(Settings.builder().put("index.number_of_shards", 4)); // <1> + request.getCreateIndexRequest().settings(Settings.builder() + .put("index.number_of_shards", 4)); // <1> // end::rollover-request-settings // tag::rollover-request-mapping request.getCreateIndexRequest().mapping("type", "field", "type=keyword"); // <1> diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java index 30275537b75..b15e0e23194 100644 --- a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java +++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java @@ -88,8 +88,8 @@ import static org.hamcrest.Matchers.greaterThan; * This class is used to generate the Java High Level REST Client Search API documentation. *

* You need to wrap your code between two tags like: - * // tag::example[] - * // end::example[] + * // tag::example + * // end::example *

* Where example is your tag name. *

@@ -98,6 +98,10 @@ import static org.hamcrest.Matchers.greaterThan; * -------------------------------------------------- * include-tagged::{doc-tests}/SearchDocumentationIT.java[example] * -------------------------------------------------- + *

+ * The column width of the code block is 84. If the code contains a line longer + * than 84, the line will be cut and a horizontal scroll bar will be displayed. + * (the code indentation of the tag is not included in the width) */ public class SearchDocumentationIT extends ESRestHighLevelClientTestCase { @@ -242,7 +246,8 @@ public class SearchDocumentationIT extends ESRestHighLevelClientTestCase { Map sourceAsMap = hit.getSourceAsMap(); String documentTitle = (String) sourceAsMap.get("title"); List users = (List) sourceAsMap.get("user"); - Map innerObject = (Map) sourceAsMap.get("innerObject"); + Map innerObject = + (Map) sourceAsMap.get("innerObject"); // end::search-hits-singleHit-source } assertEquals(3, totalHits); @@ -483,8 +488,9 @@ public class SearchDocumentationIT extends ESRestHighLevelClientTestCase { SearchResponse searchResponse = client.search(searchRequest); // tag::search-request-profiling-get - Map profilingResults = searchResponse.getProfileResults(); // <1> - for (Map.Entry profilingResult : profilingResults.entrySet()) { // <2> + Map profilingResults = + searchResponse.getProfileResults(); // <1> + for (Map.Entry profilingResult : profilingResults.entrySet()) { // <2> String key = profilingResult.getKey(); // <3> ProfileShardResult profileShardResult = profilingResult.getValue(); // <4> } @@ -494,7 +500,8 @@ public class SearchDocumentationIT extends ESRestHighLevelClientTestCase { assertNotNull(profileShardResult); // tag::search-request-profiling-queries - List queryProfileShardResults = profileShardResult.getQueryProfileResults(); // <1> + List queryProfileShardResults = + profileShardResult.getQueryProfileResults(); // <1> for (QueryProfileShardResult queryProfileResult : queryProfileShardResults) { // <2> } @@ -519,7 +526,8 @@ public class SearchDocumentationIT extends ESRestHighLevelClientTestCase { } // tag::search-request-profiling-aggs - AggregationProfileShardResult aggsProfileResults = profileShardResult.getAggregationProfileResults(); // <1> + AggregationProfileShardResult aggsProfileResults = + profileShardResult.getAggregationProfileResults(); // <1> for (ProfileResult profileResult : aggsProfileResults.getProfileResults()) { // <2> String aggName = profileResult.getQueryName(); // <3> long aggTimeInMillis = profileResult.getTime(); // <4> @@ -530,7 +538,6 @@ public class SearchDocumentationIT extends ESRestHighLevelClientTestCase { } } - @SuppressWarnings("unchecked") public void testScroll() throws Exception { RestHighLevelClient client = highLevelClient(); { @@ -602,7 +609,8 @@ public class SearchDocumentationIT extends ESRestHighLevelClientTestCase { assertEquals(3L, searchResponse.getHits().getTotalHits()); // tag::search-scroll-execute-listener - ActionListener scrollListener = new ActionListener() { + ActionListener scrollListener = + new ActionListener() { @Override public void onResponse(SearchResponse searchResponse) { // <1> @@ -652,7 +660,8 @@ public class SearchDocumentationIT extends ESRestHighLevelClientTestCase { assertThat(released, greaterThan(0)); // tag::clear-scroll-execute-listener - ActionListener listener =new ActionListener() { + ActionListener listener = + new ActionListener() { @Override public void onResponse(ClearScrollResponse clearScrollResponse) { // <1>