Checkstyle: Catch wide snippets (#34163)

We use wrap code in `// tag` and `//end` to include it in our docs. Our
current docs style wraps code snippets in a box that is only wide enough
for 76 characters and adds a horizontal scroll bar for wider snippets
which makes the snippet much harder to read. This adds a checkstyle check
that looks for java code that is included in the docs and is wider than
that 76 characters so all snippets fit into the box. It solves many of
the failures that this catches but suppresses many more. I will clean
those up in a follow up change.

Author: nik9000

buildSrc/src/main/resources/checkstyle.xml

@@ -12,11 +12,25 @@
 
   <!-- Checks Java files and forbids empty Javadoc comments -->
   <module name="RegexpMultiline">
+    <property name="id" value="EmptyJavadoc"/>
     <property name="format" value="\/\*[\s\*]*\*\/"/>
     <property name="fileExtensions" value="java"/>
     <property name="message" value="Empty javadoc comments are forbidden"/>
   </module>
 
+  <!-- 
+    We include snippets that are wrapped in `// tag` and `// end` into the
+    docs, stripping the leading spaces. If the context is wider than 76
+    characters then it'll need to scroll. This fails the build if it sees
+    such snippets.
+  -->
+  <module name="RegexpMultiline">
+    <property name="id" value="SnippetLength"/>
+    <property name="format" value="^( *)\/\/\s*tag(.+)\s*\n(.*\n)*\1.{77,}\n(.*\n)*\1\/\/\s*end\2\s*$"/>
+    <property name="fileExtensions" value="java"/>
+    <property name="message" value="Code snippets longer than 76 characters get cut off when rendered in the docs"/>
+  </module>
+
   <module name="TreeWalker">
     <!-- Its our official line length! See checkstyle_suppressions.xml for the files that don't pass this. For now we
       suppress the check there but enforce it everywhere else. This prevents the list from getting longer even if it is

buildSrc/src/main/resources/checkstyle_suppressions.xml

@@ -21,6 +21,34 @@
     configuration of classes that aren't in packages. -->
   <suppress files="test[/\\]framework[/\\]src[/\\]test[/\\]java[/\\]Dummy.java" checks="PackageDeclaration" />
 
+  <!--
+    Truly temporary suppressions suppression of snippets included in
+    documentation that are so wide that they scroll.
+  -->
+  <suppress files="client[/\\]rest-high-level[/\\]src[/\\]test[/\\]java[/\\]org[/\\]elasticsearch[/\\]client[/\\]documentation[/\\]CRUDDocumentationIT.java" id="SnippetLength" />
+  <suppress files="client[/\\]rest-high-level[/\\]src[/\\]test[/\\]java[/\\]org[/\\]elasticsearch[/\\]client[/\\]documentation[/\\]ClusterClientDocumentationIT.java" id="SnippetLength" />
+  <suppress files="client[/\\]rest-high-level[/\\]src[/\\]test[/\\]java[/\\]org[/\\]elasticsearch[/\\]client[/\\]documentation[/\\]GraphDocumentationIT.java" id="SnippetLength" />
+  <suppress files="client[/\\]rest-high-level[/\\]src[/\\]test[/\\]java[/\\]org[/\\]elasticsearch[/\\]client[/\\]documentation[/\\]IndicesClientDocumentationIT.java" id="SnippetLength" />
+  <suppress files="client[/\\]rest-high-level[/\\]src[/\\]test[/\\]java[/\\]org[/\\]elasticsearch[/\\]client[/\\]documentation[/\\]IngestClientDocumentationIT.java" id="SnippetLength" />
+  <suppress files="client[/\\]rest-high-level[/\\]src[/\\]test[/\\]java[/\\]org[/\\]elasticsearch[/\\]client[/\\]documentation[/\\]LicensingDocumentationIT.java" id="SnippetLength" />
+  <suppress files="client[/\\]rest-high-level[/\\]src[/\\]test[/\\]java[/\\]org[/\\]elasticsearch[/\\]client[/\\]documentation[/\\]MigrationDocumentationIT.java" id="SnippetLength" />
+  <suppress files="client[/\\]rest-high-level[/\\]src[/\\]test[/\\]java[/\\]org[/\\]elasticsearch[/\\]client[/\\]documentation[/\\]MigrationClientDocumentationIT.java" id="SnippetLength" />
+  <suppress files="client[/\\]rest-high-level[/\\]src[/\\]test[/\\]java[/\\]org[/\\]elasticsearch[/\\]client[/\\]documentation[/\\]MiscellaneousDocumentationIT.java" id="SnippetLength" />
+  <suppress files="client[/\\]rest-high-level[/\\]src[/\\]test[/\\]java[/\\]org[/\\]elasticsearch[/\\]client[/\\]documentation[/\\]MlClientDocumentationIT.java" id="SnippetLength" />
+  <suppress files="client[/\\]rest-high-level[/\\]src[/\\]test[/\\]java[/\\]org[/\\]elasticsearch[/\\]client[/\\]documentation[/\\]RollupDocumentationIT.java" id="SnippetLength" />
+  <suppress files="client[/\\]rest-high-level[/\\]src[/\\]test[/\\]java[/\\]org[/\\]elasticsearch[/\\]client[/\\]documentation[/\\]SearchDocumentationIT.java" id="SnippetLength" />
+  <suppress files="client[/\\]rest-high-level[/\\]src[/\\]test[/\\]java[/\\]org[/\\]elasticsearch[/\\]client[/\\]documentation[/\\]SecurityDocumentationIT.java" id="SnippetLength" />
+  <suppress files="client[/\\]rest-high-level[/\\]src[/\\]test[/\\]java[/\\]org[/\\]elasticsearch[/\\]client[/\\]documentation[/\\]SnapshotClientDocumentationIT.java" id="SnippetLength" />
+  <suppress files="client[/\\]rest-high-level[/\\]src[/\\]test[/\\]java[/\\]org[/\\]elasticsearch[/\\]client[/\\]documentation[/\\]StoredScriptsDocumentationIT.java" id="SnippetLength" />
+  <suppress files="client[/\\]rest-high-level[/\\]src[/\\]test[/\\]java[/\\]org[/\\]elasticsearch[/\\]client[/\\]documentation[/\\]TasksClientDocumentationIT.java" id="SnippetLength" />
+  <suppress files="client[/\\]rest-high-level[/\\]src[/\\]test[/\\]java[/\\]org[/\\]elasticsearch[/\\]client[/\\]documentation[/\\]WatcherDocumentationIT.java" id="SnippetLength" />
+  <!--
+    This one is in plugins/examples/script-expert-scoring but we need to
+    suppress it like this because we build that project twice, once in for
+    real and once as a test for our build system. -->
+  <suppress files="src[/\\]main[/\\]java[/\\]org[/\\]elasticsearch[/\\]example[/\\]expertscript[/\\]ExpertScriptPlugin.java" id="SnippetLength" />
+  <suppress files="modules[/\\]reindex[/\\]src[/\\]test[/\\]java[/\\]org[/\\]elasticsearch[/\\]client[/\\]documentation[/\\]ReindexDocumentationIT.jav" id="SnippetLength" />
+
   <!-- Hopefully temporary suppression of LineLength on files that don't pass it. We should remove these when we the
     files start to pass. -->
   <suppress files="client[/\\]rest[/\\]src[/\\]test[/\\]java[/\\]org[/\\]elasticsearch[/\\]client[/\\]HeapBufferedAsyncResponseConsumerTests.java" checks="LineLength" />

client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java

@@ -45,6 +45,7 @@
 import org.elasticsearch.client.ResponseListener;
 import org.elasticsearch.client.RestClient;
 import org.elasticsearch.client.RestClientBuilder;
+import org.elasticsearch.client.RestClientBuilder.HttpClientConfigCallback;
 
 import javax.net.ssl.SSLContext;
 import java.io.IOException;
@@ -93,8 +94,8 @@ public void testUsage() throws IOException, InterruptedException {
 
         //tag::rest-client-init
         RestClient restClient = RestClient.builder(
-                new HttpHost("localhost", 9200, "http"),
-                new HttpHost("localhost", 9201, "http")).build();
+            new HttpHost("localhost", 9200, "http"),
+            new HttpHost("localhost", 9201, "http")).build();
         //end::rest-client-init
 
         //tag::rest-client-close
@@ -103,26 +104,30 @@ public void testUsage() throws IOException, InterruptedException {
 
         {
             //tag::rest-client-init-default-headers
-            RestClientBuilder builder = RestClient.builder(new HttpHost("localhost", 9200, "http"));
+            RestClientBuilder builder = RestClient.builder(
+                new HttpHost("localhost", 9200, "http"));
             Header[] defaultHeaders = new Header[]{new BasicHeader("header", "value")};
             builder.setDefaultHeaders(defaultHeaders); // <1>
             //end::rest-client-init-default-headers
         }
         {
             //tag::rest-client-init-max-retry-timeout
-            RestClientBuilder builder = RestClient.builder(new HttpHost("localhost", 9200, "http"));
+            RestClientBuilder builder = RestClient.builder(
+                new HttpHost("localhost", 9200, "http"));
             builder.setMaxRetryTimeoutMillis(10000); // <1>
             //end::rest-client-init-max-retry-timeout
         }
         {
             //tag::rest-client-init-node-selector
-            RestClientBuilder builder = RestClient.builder(new HttpHost("localhost", 9200, "http"));
+            RestClientBuilder builder = RestClient.builder(
+                new HttpHost("localhost", 9200, "http"));
             builder.setNodeSelector(NodeSelector.SKIP_DEDICATED_MASTERS); // <1>
             //end::rest-client-init-node-selector
         }
         {
             //tag::rest-client-init-allocation-aware-selector
-            RestClientBuilder builder = RestClient.builder(new HttpHost("localhost", 9200, "http"));
+            RestClientBuilder builder = RestClient.builder(
+                    new HttpHost("localhost", 9200, "http"));
             builder.setNodeSelector(new NodeSelector() { // <1>
                 @Override
                 public void select(Iterable<Node> nodes) {
@@ -155,7 +160,8 @@ public void select(Iterable<Node> nodes) {
         }
         {
             //tag::rest-client-init-failure-listener
-            RestClientBuilder builder = RestClient.builder(new HttpHost("localhost", 9200, "http"));
+            RestClientBuilder builder = RestClient.builder(
+                    new HttpHost("localhost", 9200, "http"));
             builder.setFailureListener(new RestClient.FailureListener() {
                 @Override
                 public void onFailure(Node node) {
@@ -166,24 +172,30 @@ public void onFailure(Node node) {
         }
         {
             //tag::rest-client-init-request-config-callback
-            RestClientBuilder builder = RestClient.builder(new HttpHost("localhost", 9200, "http"));
-            builder.setRequestConfigCallback(new RestClientBuilder.RequestConfigCallback() {
-                @Override
-                public RequestConfig.Builder customizeRequestConfig(RequestConfig.Builder requestConfigBuilder) {
-                    return requestConfigBuilder.setSocketTimeout(10000); // <1>
-                }
-            });
+            RestClientBuilder builder = RestClient.builder(
+                    new HttpHost("localhost", 9200, "http"));
+            builder.setRequestConfigCallback(
+                new RestClientBuilder.RequestConfigCallback() {
+                    @Override
+                    public RequestConfig.Builder customizeRequestConfig(
+                            RequestConfig.Builder requestConfigBuilder) {
+                        return requestConfigBuilder.setSocketTimeout(10000); // <1>
+                    }
+                });
             //end::rest-client-init-request-config-callback
         }
         {
             //tag::rest-client-init-client-config-callback
-            RestClientBuilder builder = RestClient.builder(new HttpHost("localhost", 9200, "http"));
-            builder.setHttpClientConfigCallback(new RestClientBuilder.HttpClientConfigCallback() {
-                @Override
-                public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) {
-                    return httpClientBuilder.setProxy(new HttpHost("proxy", 9000, "http"));  // <1>
-                }
-            });
+            RestClientBuilder builder = RestClient.builder(
+                new HttpHost("localhost", 9200, "http"));
+            builder.setHttpClientConfigCallback(new HttpClientConfigCallback() {
+                    @Override
+                    public HttpAsyncClientBuilder customizeHttpClient(
+                            HttpAsyncClientBuilder httpClientBuilder) {
+                        return httpClientBuilder.setProxy(
+                            new HttpHost("proxy", 9000, "http"));  // <1>
+                    }
+                });
             //end::rest-client-init-client-config-callback
         }
 
@@ -281,58 +293,74 @@ public void onFailure(Exception exception) {
     public void testCommonConfiguration() throws Exception {
         {
             //tag::rest-client-config-timeouts
-            RestClientBuilder builder = RestClient.builder(new HttpHost("localhost", 9200))
-                    .setRequestConfigCallback(new RestClientBuilder.RequestConfigCallback() {
+            RestClientBuilder builder = RestClient.builder(
+                new HttpHost("localhost", 9200))
+                .setRequestConfigCallback(
+                    new RestClientBuilder.RequestConfigCallback() {
                         @Override
-                        public RequestConfig.Builder customizeRequestConfig(RequestConfig.Builder requestConfigBuilder) {
-                            return requestConfigBuilder.setConnectTimeout(5000)
-                                    .setSocketTimeout(60000);
+                        public RequestConfig.Builder customizeRequestConfig(
+                                RequestConfig.Builder requestConfigBuilder) {
+                            return requestConfigBuilder
+                                .setConnectTimeout(5000)
+                                .setSocketTimeout(60000);
                         }
                     })
-                    .setMaxRetryTimeoutMillis(60000);
+                .setMaxRetryTimeoutMillis(60000);
             //end::rest-client-config-timeouts
         }
         {
             //tag::rest-client-config-threads
-            RestClientBuilder builder = RestClient.builder(new HttpHost("localhost", 9200))
-                    .setHttpClientConfigCallback(new RestClientBuilder.HttpClientConfigCallback() {
-                        @Override
-                        public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) {
-                            return httpClientBuilder.setDefaultIOReactorConfig(
-                                    IOReactorConfig.custom().setIoThreadCount(1).build());
-                        }
-                    });
+            RestClientBuilder builder = RestClient.builder(
+                new HttpHost("localhost", 9200))
+                .setHttpClientConfigCallback(new HttpClientConfigCallback() {
+                    @Override
+                    public HttpAsyncClientBuilder customizeHttpClient(
+                            HttpAsyncClientBuilder httpClientBuilder) {
+                        return httpClientBuilder.setDefaultIOReactorConfig(
+                            IOReactorConfig.custom()
+                                .setIoThreadCount(1)
+                                .build());
+                    }
+                });
             //end::rest-client-config-threads
         }
         {
             //tag::rest-client-config-basic-auth
-            final CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
+            final CredentialsProvider credentialsProvider =
+                new BasicCredentialsProvider();
             credentialsProvider.setCredentials(AuthScope.ANY,
-                    new UsernamePasswordCredentials("user", "password"));
+                new UsernamePasswordCredentials("user", "password"));
 
-            RestClientBuilder builder = RestClient.builder(new HttpHost("localhost", 9200))
-                    .setHttpClientConfigCallback(new RestClientBuilder.HttpClientConfigCallback() {
-                        @Override
-                        public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) {
-                            return httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider);
-                        }
-                    });
+            RestClientBuilder builder = RestClient.builder(
+                new HttpHost("localhost", 9200))
+                .setHttpClientConfigCallback(new HttpClientConfigCallback() {
+                    @Override
+                    public HttpAsyncClientBuilder customizeHttpClient(
+                            HttpAsyncClientBuilder httpClientBuilder) {
+                        return httpClientBuilder
+                            .setDefaultCredentialsProvider(credentialsProvider);
+                    }
+                });
             //end::rest-client-config-basic-auth
         }
         {
             //tag::rest-client-config-disable-preemptive-auth
-            final CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
+            final CredentialsProvider credentialsProvider =
+                new BasicCredentialsProvider();
             credentialsProvider.setCredentials(AuthScope.ANY,
-                    new UsernamePasswordCredentials("user", "password"));
+                new UsernamePasswordCredentials("user", "password"));
 
-            RestClientBuilder builder = RestClient.builder(new HttpHost("localhost", 9200))
-                    .setHttpClientConfigCallback(new RestClientBuilder.HttpClientConfigCallback() {
-                        @Override
-                        public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) {
-                            httpClientBuilder.disableAuthCaching(); // <1>
-                            return httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider);
-                        }
-                    });
+            RestClientBuilder builder = RestClient.builder(
+                new HttpHost("localhost", 9200))
+                .setHttpClientConfigCallback(new HttpClientConfigCallback() {
+                    @Override
+                    public HttpAsyncClientBuilder customizeHttpClient(
+                            HttpAsyncClientBuilder httpClientBuilder) {
+                        httpClientBuilder.disableAuthCaching(); // <1>
+                        return httpClientBuilder
+                            .setDefaultCredentialsProvider(credentialsProvider);
+                    }
+                });
             //end::rest-client-config-disable-preemptive-auth
         }
         {
@@ -343,15 +371,18 @@ public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpCli
             try (InputStream is = Files.newInputStream(keyStorePath)) {
                 truststore.load(is, keyStorePass.toCharArray());
             }
-            SSLContextBuilder sslBuilder = SSLContexts.custom().loadTrustMaterial(truststore, null);
+            SSLContextBuilder sslBuilder = SSLContexts.custom()
+                .loadTrustMaterial(truststore, null);
             final SSLContext sslContext = sslBuilder.build();
-            RestClientBuilder builder = RestClient.builder(new HttpHost("localhost", 9200, "https"))
-                    .setHttpClientConfigCallback(new RestClientBuilder.HttpClientConfigCallback() {
-                        @Override
-                        public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) {
-                            return httpClientBuilder.setSSLContext(sslContext);
-                        }
-                    });
+            RestClientBuilder builder = RestClient.builder(
+                new HttpHost("localhost", 9200, "https"))
+                .setHttpClientConfigCallback(new HttpClientConfigCallback() {
+                    @Override
+                    public HttpAsyncClientBuilder customizeHttpClient(
+                            HttpAsyncClientBuilder httpClientBuilder) {
+                        return httpClientBuilder.setSSLContext(sslContext);
+                    }
+                });
             //end::rest-client-config-encrypted-communication
         }
     }