[Javadocs] add remaining internal classes and reenable missingJavadoc…

… on server (#3296) Adds the remaining javadocs to internal classes and reenables the missingJavadoc gradle task on the server module. From here forward if class level javadocs are missing in the server module, gradle check will fail! Signed-off-by: Nicholas Walter Knize <[email protected]>
opensearch-project · May 12, 2022 · 3aef125 · 3aef125
1 parent 10bff0c
commit 3aef125
Show file tree

Hide file tree

Showing 185 changed files with 1,613 additions and 12 deletions.
diff --git a/gradle/missing-javadoc.gradle b/gradle/missing-javadoc.gradle
@@ -178,8 +178,7 @@ configure([
 
 configure(project(":server")) {
   project.tasks.withType(MissingJavadocTask) {
-    isExcluded = true
-    // TODO: reenable after fixing missing javadocs
+    // TODO: bump to variable missing level after increasing javadoc coverage
     javadocMissingLevel = "class"
   }
 }

diff --git a/server/src/main/java/org/opensearch/action/IndicesRequest.java b/server/src/main/java/org/opensearch/action/IndicesRequest.java
@@ -64,6 +64,11 @@ default boolean includeDataStreams() {
         return false;
     }
 
+    /**
+     * Replaceable interface.
+     *
+     * @opensearch.internal
+     */
     interface Replaceable extends IndicesRequest {
         /**
          * Sets the indices that the action relates to.

diff --git a/server/src/main/java/org/opensearch/action/admin/cluster/health/ClusterHealthRequest.java b/server/src/main/java/org/opensearch/action/admin/cluster/health/ClusterHealthRequest.java
@@ -289,6 +289,11 @@ public ActionRequestValidationException validate() {
         return null;
     }
 
+    /**
+     * The level of the health request.
+     *
+     * @opensearch.internal
+     */
     public enum Level {
         CLUSTER,
         INDICES,

diff --git a/server/src/main/java/org/opensearch/action/admin/indices/alias/IndicesAliasesRequest.java b/server/src/main/java/org/opensearch/action/admin/indices/alias/IndicesAliasesRequest.java
@@ -120,6 +120,11 @@ public static class AliasActions implements AliasesRequest, Writeable, ToXConten
         private static final ParseField REMOVE = new ParseField("remove");
         private static final ParseField REMOVE_INDEX = new ParseField("remove_index");
 
+        /**
+         * The type of request.
+         *
+         * @opensearch.internal
+         */
         public enum Type {
             ADD((byte) 0, AliasActions.ADD),
             REMOVE((byte) 1, AliasActions.REMOVE),

diff --git a/server/src/main/java/org/opensearch/action/admin/indices/get/GetIndexRequest.java b/server/src/main/java/org/opensearch/action/admin/indices/get/GetIndexRequest.java
@@ -46,6 +46,11 @@
  * @opensearch.internal
  */
 public class GetIndexRequest extends ClusterInfoRequest<GetIndexRequest> {
+    /**
+     * The features to get.
+     *
+     * @opensearch.internal
+     */
     public enum Feature {
         ALIASES((byte) 0),
         MAPPINGS((byte) 1),

diff --git a/server/src/main/java/org/opensearch/action/admin/indices/stats/CommonStatsFlags.java b/server/src/main/java/org/opensearch/action/admin/indices/stats/CommonStatsFlags.java
@@ -261,6 +261,11 @@ public CommonStatsFlags clone() {
         }
     }
 
+    /**
+     * The flags.
+     *
+     * @opensearch.internal
+     */
     public enum Flag {
         Store("store", 0),
         Indexing("indexing", 1),

diff --git a/server/src/main/java/org/opensearch/action/search/TransportSearchAction.java b/server/src/main/java/org/opensearch/action/search/TransportSearchAction.java
@@ -284,6 +284,11 @@ protected void doExecute(Task task, SearchRequest searchRequest, ActionListener<
         executeRequest(task, searchRequest, this::searchAsyncAction, listener);
     }
 
+    /**
+     * The single phase search action.
+     *
+     * @opensearch.internal
+     */
     public interface SinglePhaseSearchAction {
         void executeOnShardTarget(
             SearchTask searchTask,

diff --git a/server/src/main/java/org/opensearch/action/support/IndicesOptions.java b/server/src/main/java/org/opensearch/action/support/IndicesOptions.java
@@ -60,6 +60,11 @@
  */
 public class IndicesOptions implements ToXContentFragment {
 
+    /**
+     * The wildcard states.
+     *
+     * @opensearch.internal
+     */
     public enum WildcardStates {
         OPEN,
         CLOSED,
@@ -120,6 +125,11 @@ private static void updateSetForValue(EnumSet<WildcardStates> states, String wil
         }
     }
 
+    /**
+     * The options.
+     *
+     * @opensearch.internal
+     */
     public enum Option {
         IGNORE_UNAVAILABLE,
         IGNORE_ALIASES,

diff --git a/server/src/main/java/org/opensearch/action/support/WriteRequest.java b/server/src/main/java/org/opensearch/action/support/WriteRequest.java
@@ -75,6 +75,11 @@ default R setRefreshPolicy(String refreshPolicy) {
 
     ActionRequestValidationException validate();
 
+    /**
+     * The refresh policy of the request.
+     *
+     * @opensearch.internal
+     */
     enum RefreshPolicy implements Writeable {
         /**
          * Don't refresh after this request. The default.

diff --git a/server/src/main/java/org/opensearch/action/support/replication/ReplicationOperation.java b/server/src/main/java/org/opensearch/action/support/replication/ReplicationOperation.java
@@ -616,6 +616,11 @@ public RetryOnPrimaryException(StreamInput in) throws IOException {
         }
     }
 
+    /**
+     * The result of the primary.
+     *
+     * @opensearch.internal
+     */
     public interface PrimaryResult<RequestT extends ReplicationRequest<RequestT>> {
 
         /**

diff --git a/server/src/main/java/org/opensearch/action/termvectors/TermVectorsRequest.java b/server/src/main/java/org/opensearch/action/termvectors/TermVectorsRequest.java
@@ -568,6 +568,11 @@ public void writeTo(StreamOutput out) throws IOException {
         out.writeLong(version);
     }
 
+    /**
+     * The flags.
+     *
+     * @opensearch.internal
+     */
     public enum Flag {
         // Do not change the order of these flags we use
         // the ordinal for encoding! Only append to the end!

diff --git a/server/src/main/java/org/opensearch/bootstrap/jvm/DenyJvmVersionsParser.java b/server/src/main/java/org/opensearch/bootstrap/jvm/DenyJvmVersionsParser.java
@@ -24,8 +24,15 @@
 /**
  * Parses the list of JVM versions which should be denied to run Opensearch engine with due to discovered
  * issues or flaws.
+ *
+ * @opensearch.internal
  */
 public class DenyJvmVersionsParser {
+    /**
+     * Provides the reason for the denial
+     *
+     * @opensearch.internal
+     */
     public interface VersionPredicate extends Predicate<Version> {
         String getReason();
     }

diff --git a/server/src/main/java/org/opensearch/bootstrap/jvm/package-info.java b/server/src/main/java/org/opensearch/bootstrap/jvm/package-info.java
@@ -0,0 +1,10 @@
+/*
+ * 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.
+ */
+
+/** jvm specific bootstrapping */
+package org.opensearch.bootstrap.jvm;
diff --git a/server/src/main/java/org/opensearch/cluster/AbstractDiffable.java b/server/src/main/java/org/opensearch/cluster/AbstractDiffable.java
@@ -66,6 +66,11 @@ public static <T extends Diffable<T>> Diff<T> readDiffFrom(Reader<T> reader, Str
         return (Diff<T>) EMPTY;
     }
 
+    /**
+     * A complete diff.
+     *
+     * @opensearch.internal
+     */
     private static class CompleteDiff<T extends Diffable<T>> implements Diff<T> {
 
         @Nullable

diff --git a/server/src/main/java/org/opensearch/cluster/AbstractNamedDiffable.java b/server/src/main/java/org/opensearch/cluster/AbstractNamedDiffable.java
@@ -62,6 +62,11 @@ public static <T extends NamedDiffable<T>> NamedDiff<T> readDiffFrom(Class<? ext
         return new CompleteNamedDiff<>(tClass, name, in);
     }
 
+    /**
+     * A complete named diff.
+     *
+     * @opensearch.internal
+     */
     private static class CompleteNamedDiff<T extends NamedDiffable<T>> implements NamedDiff<T> {
 
         @Nullable

diff --git a/server/src/main/java/org/opensearch/cluster/ClusterInfo.java b/server/src/main/java/org/opensearch/cluster/ClusterInfo.java
@@ -244,6 +244,8 @@ static String shardIdentifierFromRouting(ShardRouting shardRouting) {
 
     /**
      * Represents a data path on a node
+     *
+     * @opensearch.internal
      */
     public static class NodeAndPath implements Writeable {
         public final String nodeId;
@@ -281,6 +283,8 @@ public void writeTo(StreamOutput out) throws IOException {
 
     /**
      * Represents the total amount of "reserved" space on a particular data path, together with the set of shards considered.
+     *
+     * @opensearch.internal
      */
     public static class ReservedSpace implements Writeable {
 
@@ -344,6 +348,11 @@ void toXContent(XContentBuilder builder, Params params) throws IOException {
             builder.endArray(); // end "shards"
         }
 
+        /**
+         * Builder for Reserved Space.
+         *
+         * @opensearch.internal
+         */
         public static class Builder {
             private long total;
             private ObjectHashSet<ShardId> shardIds = new ObjectHashSet<>();

diff --git a/server/src/main/java/org/opensearch/cluster/ClusterState.java b/server/src/main/java/org/opensearch/cluster/ClusterState.java
@@ -106,6 +106,8 @@ public class ClusterState implements ToXContentFragment, Diffable<ClusterState>
 
     /**
      * An interface that implementors use when a class requires a client to maybe have a feature.
+     *
+     * @opensearch.internal
      */
     public interface FeatureAware {
 
@@ -135,6 +137,11 @@ static <T extends VersionedNamedWriteable & FeatureAware> boolean shouldSerializ
 
     }
 
+    /**
+     * Custom cluster state.
+     *
+     * @opensearch.internal
+     */
     public interface Custom extends NamedDiffable<Custom>, ToXContentFragment, FeatureAware {
 
         /**
@@ -403,6 +410,11 @@ public boolean supersedes(ClusterState other) {
 
     }
 
+    /**
+     * Metrics for cluster state.
+     *
+     * @opensearch.internal
+     */
     public enum Metric {
         VERSION("version"),
 
@@ -582,6 +594,11 @@ public static Builder builder(ClusterState state) {
         return new Builder(state);
     }
 
+    /**
+     * Builder for cluster state.
+     *
+     * @opensearch.internal
+     */
     public static class Builder {
 
         private final ClusterName clusterName;
@@ -778,6 +795,11 @@ public void writeTo(StreamOutput out) throws IOException {
         out.writeVInt(minimumClusterManagerNodesOnPublishingClusterManager);
     }
 
+    /**
+     * The cluster state diff.
+     *
+     * @opensearch.internal
+     */
     private static class ClusterStateDiff implements Diff<ClusterState> {
 
         private final long toVersion;

diff --git a/server/src/main/java/org/opensearch/cluster/ClusterStateObserver.java b/server/src/main/java/org/opensearch/cluster/ClusterStateObserver.java
@@ -207,6 +207,11 @@ public void waitForNextChange(Listener listener, Predicate<ClusterState> statePr
         }
     }
 
+    /**
+     * An observer of the cluster state for changes.
+     *
+     * @opensearch.internal
+     */
     class ObserverClusterStateListener implements TimeoutClusterStateListener {
 
         @Override
@@ -298,6 +303,8 @@ public String toString() {
 
     /**
      * The observer considers two cluster states to be the same if they have the same version and cluster-manager node id (i.e. null or set)
+     *
+     * @opensearch.internal
      */
     private static class StoredState {
         private final String clusterManagerNodeId;
@@ -317,6 +324,11 @@ public boolean isOlderOrDifferentClusterManager(ClusterState clusterState) {
         }
     }
 
+    /**
+     * Listener for the observer.
+     *
+     * @opensearch.internal
+     */
     public interface Listener {
 
         /** called when a new state is observed */
@@ -328,6 +340,11 @@ public interface Listener {
         void onTimeout(TimeValue timeout);
     }
 
+    /**
+     * Context for the observer.
+     *
+     * @opensearch.internal
+     */
     static class ObservingContext {
         public final Listener listener;
         public final Predicate<ClusterState> statePredicate;
@@ -343,6 +360,11 @@ public String toString() {
         }
     }
 
+    /**
+     * A context preserving listener.
+     *
+     * @opensearch.internal
+     */
     private static final class ContextPreservingListener implements Listener {
         private final Listener delegate;
         private final Supplier<ThreadContext.StoredContext> contextSupplier;

diff --git a/server/src/main/java/org/opensearch/cluster/ClusterStateTaskConfig.java b/server/src/main/java/org/opensearch/cluster/ClusterStateTaskConfig.java
@@ -85,6 +85,11 @@ static ClusterStateTaskConfig build(Priority priority, TimeValue timeout) {
         return new Basic(priority, timeout);
     }
 
+    /**
+     * Basic task config.
+     *
+     * @opensearch.internal
+     */
     class Basic implements ClusterStateTaskConfig {
         final TimeValue timeout;
         final Priority priority;

diff --git a/server/src/main/java/org/opensearch/cluster/ClusterStateTaskExecutor.java b/server/src/main/java/org/opensearch/cluster/ClusterStateTaskExecutor.java
@@ -81,6 +81,8 @@ default String describeTasks(List<T> tasks) {
     /**
      * Represents the result of a batched execution of cluster state update tasks
      * @param <T> the type of the cluster state update task
+     *
+     * @opensearch.internal
      */
     class ClusterTasksResult<T> {
         @Nullable
@@ -101,6 +103,11 @@ public static <T> Builder<T> builder() {
             return new Builder<>();
         }
 
+        /**
+         * Builder for cluster state task.
+         *
+         * @opensearch.internal
+         */
         public static class Builder<T> {
             private final Map<T, TaskResult> executionResults = new IdentityHashMap<>();
 
@@ -142,6 +149,11 @@ ClusterTasksResult<T> build(ClusterTasksResult<T> result, ClusterState previousS
         }
     }
 
+    /**
+     * The task result.
+     *
+     * @opensearch.internal
+     */
     final class TaskResult {
         private final Exception failure;
-Original file line number
+Diff line change
@@ Expand Up @@
             }
         }
+        /**
+         * The result of the primary.
+         *
+         * @opensearch.internal
+         */
         public interface PrimaryResult<RequestT extends ReplicationRequest<RequestT>> {
             /**
@@ Expand Down @@