Merging javadoc feature branch changes to main (opensearch-project#715)

* Adds a gradle plugin to validate missing javadocs Use `./gradlew missingJavadoc` to validate missing javadocs. Currently this task fails because several modules are missing appropriate javadocs. Once added, this should pass. Also, precommit PomValidation check currently fails with missing Javadoc plugin, that needs to be fixed - opensearch-project#449 Thus keeping this in a separate feature branch. Signed-off-by: Himanshu Setia <[email protected]> * Fix Javadoc errors in module `client/rest` (opensearch-project#685) * Fix Javadoc errors in client/rest module Signed-off-by: Gregor Zurowski <[email protected]> * Add package info file in client/rest module Signed-off-by: Gregor Zurowski <[email protected]> * Fix typos Signed-off-by: Gregor Zurowski <[email protected]> * Add exception documentation to Javadoc Signed-off-by: Gregor Zurowski <[email protected]> * Fixes precommit task configuration failures due to newly added missin… (opensearch-project#707) * Fixes precommit task configuration failures due to newly added missingJavadoc task Signed-off-by: Himanshu Setia <[email protected]> * Fixes javadoc task errors due to PR#685 Signed-off-by: Himanshu Setia <[email protected]> * Updated CONTRIBUTING.md for info on javadocs Signed-off-by: Himanshu Setia <[email protected]> * Correcting licenses and naming Signed-off-by: Himanshu Setia <[email protected]> * Correcting version info Signed-off-by: Himanshu Setia <[email protected]> Co-authored-by: Gregor Zurowski <[email protected]>
sumitasr · May 18, 2021 · 6f893ed · 6f893ed
1 parent 50abf6d
commit 6f893ed
Show file tree

Hide file tree

Showing 30 changed files with 892 additions and 3 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -53,6 +53,7 @@ If you've thought of a way that OpenSearch could be better, we want to hear abou
 ### Documentation Changes
 
 If you would like to contribute to the documentation, please see [OpenSearch Docs repo](https://github.com/opensearch-project/documentation-website/blob/main/README.md).
+To contribute javadocs, please see [this open issue on github](https://github.com/opensearch-project/OpenSearch/issues/221).
 
 ### Contributing Code
 

diff --git a/build.gradle b/build.gradle
@@ -58,6 +58,7 @@ apply from: 'gradle/formatting.gradle'
 apply from: 'gradle/local-distribution.gradle'
 apply from: 'gradle/fips.gradle'
 apply from: 'gradle/run.gradle'
+apply from: 'gradle/missing-javadoc.gradle'
 
 // common maven publishing configuration
 allprojects {

diff --git a/buildSrc/reaper/src/main/java/org/opensearch/gradle/reaper/package-info.java b/buildSrc/reaper/src/main/java/org/opensearch/gradle/reaper/package-info.java
@@ -0,0 +1,12 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+
+/**
+ * A standalone process that will reap external services after a build dies.
+ */
+package org.opensearch.gradle.reaper;
diff --git a/client/rest/src/main/java/org/opensearch/client/HasAttributeNodeSelector.java b/client/rest/src/main/java/org/opensearch/client/HasAttributeNodeSelector.java
@@ -45,6 +45,13 @@ public final class HasAttributeNodeSelector implements NodeSelector {
     private final String key;
     private final String value;
 
+    /**
+     * Create a {link HasAttributeNodeSelector} instance using the provided
+     * attribute key value pair.
+     *
+     * @param key The attribute name.
+     * @param value The attribute value.
+     */
     public HasAttributeNodeSelector(String key, String value) {
         this.key = key;
         this.value = value;

diff --git a/client/rest/src/main/java/org/opensearch/client/HeapBufferedAsyncResponseConsumer.java b/client/rest/src/main/java/org/opensearch/client/HeapBufferedAsyncResponseConsumer.java
@@ -61,7 +61,10 @@ public class HeapBufferedAsyncResponseConsumer extends AbstractAsyncResponseCons
     private volatile SimpleInputBuffer buf;
 
     /**
-     * Creates a new instance of this consumer with the provided buffer limit
+     * Creates a new instance of this consumer with the provided buffer limit.
+     *
+     * @param bufferLimit the buffer limit. Must be greater than 0.
+     * @throws IllegalArgumentException if {@code bufferLimit} is less than or equal to 0.
      */
     public HeapBufferedAsyncResponseConsumer(int bufferLimit) {
         if (bufferLimit <= 0) {

diff --git a/client/rest/src/main/java/org/opensearch/client/HttpAsyncResponseConsumerFactory.java b/client/rest/src/main/java/org/opensearch/client/HttpAsyncResponseConsumerFactory.java
@@ -66,6 +66,11 @@ class HeapBufferedResponseConsumerFactory implements HttpAsyncResponseConsumerFa
 
         private final int bufferLimit;
 
+        /**
+         * Creates a {@link HeapBufferedResponseConsumerFactory} instance with the given buffer limit.
+         *
+         * @param bufferLimitBytes the buffer limit to be applied to this instance
+         */
         public HeapBufferedResponseConsumerFactory(int bufferLimitBytes) {
             this.bufferLimit = bufferLimitBytes;
         }

diff --git a/client/rest/src/main/java/org/opensearch/client/Node.java b/client/rest/src/main/java/org/opensearch/client/Node.java
@@ -77,6 +77,13 @@ public class Node {
      * Create a {@linkplain Node} with metadata. All parameters except
      * {@code host} are nullable and implementations of {@link NodeSelector}
      * need to decide what to do in their absence.
+     *
+     * @param host       primary host address
+     * @param boundHosts addresses on which the host is listening
+     * @param name       name of the node
+     * @param version    version of OpenSearch
+     * @param roles      roles that the OpenSearch process has on the host
+     * @param attributes attributes declared on the node
      */
     public Node(HttpHost host, Set<HttpHost> boundHosts, String name, String version,
             Roles roles, Map<String, List<String>> attributes) {
@@ -93,6 +100,8 @@ public Node(HttpHost host, Set<HttpHost> boundHosts, String name, String version
 
     /**
      * Create a {@linkplain Node} without any metadata.
+     *
+     * @param host primary host address
      */
     public Node(HttpHost host) {
         this(host, null, null, null, null, null);
@@ -192,6 +201,11 @@ public static final class Roles {
 
         private final Set<String> roles;
 
+        /**
+         * Create a {@link Roles} instance of the given string set.
+         *
+         * @param roles set of role names.
+         */
         public Roles(final Set<String> roles) {
             this.roles = new TreeSet<>(roles);
         }

diff --git a/client/rest/src/main/java/org/opensearch/client/NodeSelector.java b/client/rest/src/main/java/org/opensearch/client/NodeSelector.java
@@ -53,6 +53,8 @@ public interface NodeSelector {
      * {@link RestClient} will call this method with a list of "dead" nodes.
      * <p>
      * Implementers should not rely on the ordering of the nodes.
+     *
+     * @param nodes the {@link Node}s targeted for the sending requests
      */
     void select(Iterable<Node> nodes);
     /*

diff --git a/client/rest/src/main/java/org/opensearch/client/PreferHasAttributeNodeSelector.java b/client/rest/src/main/java/org/opensearch/client/PreferHasAttributeNodeSelector.java
@@ -47,6 +47,12 @@ public final class PreferHasAttributeNodeSelector implements NodeSelector {
     private final String key;
     private final String value;
 
+    /**
+     * Creates a {@link PreferHasAttributeNodeSelector} instance with the given key value pair.
+     *
+     * @param key attribute key
+     * @param value attribute value
+     */
     public PreferHasAttributeNodeSelector(String key, String value) {
         this.key = key;
         this.value = value;

diff --git a/client/rest/src/main/java/org/opensearch/client/Request.java b/client/rest/src/main/java/org/opensearch/client/Request.java
@@ -94,6 +94,12 @@ public void addParameter(String name, String value) {
         }
     }
 
+    /**
+     * Add query parameters using the provided map of key value pairs.
+     *
+     * @param paramSource a map of key value pairs where the key is the url parameter.
+     * @throws IllegalArgumentException if a parameter with that name has already been set.
+     */
     public void addParameters(Map<String, String> paramSource){
         paramSource.forEach(this::addParameter);
     }
@@ -110,6 +116,8 @@ public Map<String, String> getParameters() {
     /**
      * Set the body of the request. If not set or set to {@code null} then no
      * body is sent with the request.
+     *
+     * @param entity the {@link HttpEntity} to be set as the body of the request.
      */
     public void setEntity(HttpEntity entity) {
         this.entity = entity;
@@ -121,6 +129,8 @@ public void setEntity(HttpEntity entity) {
      * {@code Content-Type} will be sent as {@code application/json}.
      * If you need a different content type then use
      * {@link #setEntity(HttpEntity)}.
+     *
+     * @param entity JSON string to be set as the entity body of the request.
      */
     public void setJsonEntity(String entity) {
         setEntity(entity == null ? null : new NStringEntity(entity, ContentType.APPLICATION_JSON));
@@ -137,6 +147,9 @@ public HttpEntity getEntity() {
     /**
      * Set the portion of an HTTP request to OpenSearch that can be
      * manipulated without changing OpenSearch's behavior.
+     *
+     * @param options the options to be set.
+     * @throws NullPointerException if {@code options} is null.
      */
     public void setOptions(RequestOptions options) {
         Objects.requireNonNull(options, "options cannot be null");
@@ -146,6 +159,9 @@ public void setOptions(RequestOptions options) {
     /**
      * Set the portion of an HTTP request to OpenSearch that can be
      * manipulated without changing OpenSearch's behavior.
+     *
+     * @param options the options to be set.
+     * @throws NullPointerException if {@code options} is null.
      */
     public void setOptions(RequestOptions.Builder options) {
         Objects.requireNonNull(options, "options cannot be null");

diff --git a/client/rest/src/main/java/org/opensearch/client/RequestOptions.java b/client/rest/src/main/java/org/opensearch/client/RequestOptions.java
@@ -196,6 +196,10 @@ public RequestOptions build() {
 
         /**
          * Add the provided header to the request.
+         *
+         * @param name  the header name
+         * @param value the header value
+         * @throws NullPointerException if {@code name} or {@code value} is null.
          */
         public Builder addHeader(String name, String value) {
             Objects.requireNonNull(name, "header name cannot be null");
@@ -209,6 +213,9 @@ public Builder addHeader(String name, String value) {
          * {@link HttpAsyncResponseConsumer} callback per retry. Controls how the
          * response body gets streamed from a non-blocking HTTP connection on the
          * client side.
+         *
+         * @param httpAsyncResponseConsumerFactory factory for creating {@link HttpAsyncResponseConsumer}.
+         * @throws NullPointerException if {@code httpAsyncResponseConsumerFactory} is null.
          */
         public void setHttpAsyncResponseConsumerFactory(HttpAsyncResponseConsumerFactory httpAsyncResponseConsumerFactory) {
             this.httpAsyncResponseConsumerFactory =
@@ -231,6 +238,8 @@ public void setHttpAsyncResponseConsumerFactory(HttpAsyncResponseConsumerFactory
          * {@linkplain WarningsHandler} to permit only certain warnings or to
          * fail the request if the warnings returned don't
          * <strong>exactly</strong> match some set.
+         *
+         * @param warningsHandler the {@link WarningsHandler} to be used
          */
         public void setWarningsHandler(WarningsHandler warningsHandler) {
             this.warningsHandler = warningsHandler;

diff --git a/client/rest/src/main/java/org/opensearch/client/Response.java b/client/rest/src/main/java/org/opensearch/client/Response.java
@@ -96,6 +96,8 @@ public Header[] getHeaders() {
      * Returns the value of the first header with a specified name of this message.
      * If there is more than one matching header in the message the first element is returned.
      * If there is no matching header in the message <code>null</code> is returned.
+     *
+     * @param name header name
      */
     public String getHeader(String name) {
         Header header = response.getFirstHeader(name);

diff --git a/client/rest/src/main/java/org/opensearch/client/ResponseException.java b/client/rest/src/main/java/org/opensearch/client/ResponseException.java
@@ -47,6 +47,11 @@ public final class ResponseException extends IOException {
 
     private final Response response;
 
+    /**
+     * Creates a ResponseException containing the given {@code Response}.
+     *
+     * @param response The error response.
+     */
     public ResponseException(Response response) throws IOException {
         super(buildMessage(response));
         this.response = response;

diff --git a/client/rest/src/main/java/org/opensearch/client/ResponseListener.java b/client/rest/src/main/java/org/opensearch/client/ResponseListener.java
@@ -44,14 +44,18 @@
 public interface ResponseListener {
 
     /**
-     * Method invoked if the request yielded a successful response
+     * Method invoked if the request yielded a successful response.
+     *
+     * @param response success response
      */
     void onSuccess(Response response);
 
     /**
      * Method invoked if the request failed. There are two main categories of failures: connection failures (usually
      * {@link java.io.IOException}s, or responses that were treated as errors based on their error response code
      * ({@link ResponseException}s).
+     *
+     * @param exception the failure exception
      */
     void onFailure(Exception exception);
 }
diff --git a/client/rest/src/main/java/org/opensearch/client/RestClient.java b/client/rest/src/main/java/org/opensearch/client/RestClient.java
@@ -195,6 +195,8 @@ public static RestClientBuilder builder(String cloudId) {
      * <p>
      * Prefer this to {@link #builder(HttpHost...)} if you have metadata up front about the nodes.
      * If you don't either one is fine.
+     *
+     * @param nodes The nodes that the client will send requests to.
      */
     public static RestClientBuilder builder(Node... nodes) {
         return new RestClientBuilder(nodes == null ? null : Arrays.asList(nodes));
@@ -207,6 +209,8 @@ public static RestClientBuilder builder(Node... nodes) {
      * You can use this if you do not have metadata up front about the nodes. If you do, prefer
      * {@link #builder(Node...)}.
      * @see Node#Node(HttpHost)
+     *
+     * @param hosts The hosts that the client will send requests to.
      */
     public static RestClientBuilder builder(HttpHost... hosts) {
         if (hosts == null || hosts.length == 0) {
@@ -218,6 +222,8 @@ public static RestClientBuilder builder(HttpHost... hosts) {
 
     /**
      * Replaces the nodes with which the client communicates.
+     *
+     * @param nodes the new nodes to communicate with.
      */
     public synchronized void setNodes(Collection<Node> nodes) {
         if (nodes == null || nodes.isEmpty()) {
@@ -672,7 +678,14 @@ void trackFailure(Exception exception) {
      */
     public static class FailureListener {
         /**
-         * Notifies that the node provided as argument has just failed
+         * Create a {@link FailureListener} instance.
+         */
+        public FailureListener() {}
+
+        /**
+         * Notifies that the node provided as argument has just failed.
+         *
+         * @param node The node which has failed.
          */
         public void onFailure(Node node) {}
     }
@@ -907,6 +920,11 @@ private static Exception extractAndWrapCause(Exception exception) {
      */
     public static class ContentCompressingEntity extends GzipCompressingEntity {
 
+        /**
+         * Creates a {@link ContentCompressingEntity} instance with the provided HTTP entity.
+         *
+         * @param entity the HTTP entity.
+         */
         public ContentCompressingEntity(HttpEntity entity) {
             super(entity);
         }