[Javadoc] add missing javadocs for :example-plugin modules (#4540)

* Add javadocs for example-plugins:custom-settings module Signed-off-by: Daniel Widdis <widdis@gmail.com> * Add javadocs for example-plugins:custom-significance-heuristic Signed-off-by: Daniel Widdis <widdis@gmail.com> * Add javadocs for example-plugins:custom-suggester Signed-off-by: Daniel Widdis <widdis@gmail.com> * Add javadocs to example-plugins:painless-allowlist Signed-off-by: Daniel Widdis <widdis@gmail.com> * Add javadocs to example-plugins:rescore Signed-off-by: Daniel Widdis <widdis@gmail.com> * Add javadocs to example-plugins:rest-handler Signed-off-by: Daniel Widdis <widdis@gmail.com> * Add javadocs to example-plugins:script-expert-scoring Signed-off-by: Daniel Widdis <widdis@gmail.com> * Remove exclusions for module which aren't giving javadoc errors Signed-off-by: Daniel Widdis <widdis@gmail.com> * CI testing apparently needs to instantiate a no-op class Signed-off-by: Daniel Widdis <widdis@gmail.com> Signed-off-by: Daniel Widdis <widdis@gmail.com>
opensearch-project · Sep 19, 2022 · fa07cd9 · fa07cd9
1 parent 4657716
commit fa07cd9
Show file tree

Hide file tree

Showing 30 changed files with 460 additions and 23 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -18,6 +18,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added missing javadocs for `:distribution:tools` modules ([#4483](https://github.com/opensearch-project/OpenSearch/pull/4483))
 - Add BWC version 2.3.1 ([#4513](https://github.com/opensearch-project/OpenSearch/pull/4513))
 - [Segment Replication] Add snapshot and restore tests for segment replication feature ([#3993](https://github.com/opensearch-project/OpenSearch/pull/3993))
+- Added missing javadocs for `:example-plugins` modules ([#4540](https://github.com/opensearch-project/OpenSearch/pull/4540))
 
 ### Dependencies
 - Bumps `reactive-streams` from 1.0.3 to 1.0.4

diff --git a/gradle/missing-javadoc.gradle b/gradle/missing-javadoc.gradle
@@ -95,14 +95,6 @@ configure([
   project(":client:client-benchmark-noop-api-plugin"),
   project(":client:rest-high-level"),
   project(":client:test"),
-  project(":doc-tools"),
-  project(":example-plugins:custom-settings"),
-  project(":example-plugins:custom-significance-heuristic"),
-  project(":example-plugins:custom-suggester"),
-  project(":example-plugins:painless-allowlist"),
-  project(":example-plugins:rescore"),
-  project(":example-plugins:rest-handler"),
-  project(":example-plugins:script-expert-scoring"),
   project(":libs:opensearch-cli"),
   project(":libs:opensearch-core"),
   project(":libs:opensearch-dissect"),
@@ -155,9 +147,7 @@ configure([
   project(":plugins:store-smb"),
   project(":plugins:transport-nio"),
   project(":qa:die-with-dignity"),
-  project(":qa:os"),
   project(":qa:wildfly"),
-  project(":rest-api-spec"),
   project(":test:external-modules:test-delayed-aggs"),
   project(":test:fixtures:azure-fixture"),
   project(":test:fixtures:gcs-fixture"),

diff --git a/...ings/src/main/java/org/opensearch/example/customsettings/ExampleCustomSettingsConfig.java b/...ings/src/main/java/org/opensearch/example/customsettings/ExampleCustomSettingsConfig.java
@@ -94,8 +94,13 @@ public class ExampleCustomSettingsConfig {
     private final List<Integer> list;
     private final String filtered;
 
+    /**
+     * Instantiate this object based on the specified environment.
+     *
+     * @param environment The environment including paths to custom setting configuration files
+     */
     public ExampleCustomSettingsConfig(final Environment environment) {
-        // Elasticsearch config directory
+        // OpenSearch config directory
         final Path configDir = environment.configDir();
 
         // Resolve the plugin's custom settings file
@@ -121,22 +126,47 @@ public ExampleCustomSettingsConfig(final Environment environment) {
         assert secured != null;
     }
 
+    /**
+     * Gets the value of the custom.simple String setting.
+     *
+     * @return the custom.simple value
+     */
     public String getSimple() {
         return simple;
     }
 
+    /**
+     * Gets the value of the custom.bool boolean setting.
+     *
+     * @return the custom.bool value
+     */
     public Boolean getBool() {
         return bool;
     }
 
+    /**
+     * Gets the value of the custom.validated String setting.
+     *
+     * @return the custom.validated value
+     */
     public String getValidated() {
         return validated;
     }
 
+    /**
+     * Gets the value of the custom.filtered String setting.
+     *
+     * @return the custom.filtered value
+     */
     public String getFiltered() {
         return filtered;
     }
 
+    /**
+     * Gets the value of the custom.list list of integers setting.
+     *
+     * @return the custom.list value
+     */
     public List<Integer> getList() {
         return list;
     }

diff --git a/...ings/src/main/java/org/opensearch/example/customsettings/ExampleCustomSettingsPlugin.java b/...ings/src/main/java/org/opensearch/example/customsettings/ExampleCustomSettingsPlugin.java
@@ -42,20 +42,26 @@
 
 import static java.util.stream.Collectors.toList;
 
+/**
+ * An example plugin that includes custom settings.
+ */
 public class ExampleCustomSettingsPlugin extends Plugin {
 
     private final ExampleCustomSettingsConfig config;
 
+    /**
+     * Instantiate this plugin with the specified settings and config path.
+     *
+     * @param settings The settings for this plugin.
+     * @param configPath The path to this plugin's configuration files.
+     */
     public ExampleCustomSettingsPlugin(final Settings settings, final Path configPath) {
         this.config = new ExampleCustomSettingsConfig(new Environment(settings, configPath));
 
         // asserts that the setting has been correctly loaded from the custom setting file
         assert "secret".equals(config.getFiltered());
     }
 
-    /**
-     * @return the plugin's custom settings
-     */
     @Override
     public List<Setting<?>> getSettings() {
         return Arrays.asList(

diff --git a/...les/custom-settings/src/main/java/org/opensearch/example/customsettings/package-info.java b/...les/custom-settings/src/main/java/org/opensearch/example/customsettings/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.
+ */
+
+/**
+ * Example classes demonstrating the use of custom settings in a plugin.
+ */
+package org.opensearch.example.customsettings;
diff --git a/...ain/java/org/opensearch/example/customsigheuristic/CustomSignificanceHeuristicPlugin.java b/...ain/java/org/opensearch/example/customsigheuristic/CustomSignificanceHeuristicPlugin.java
@@ -44,6 +44,12 @@
  * Plugin declaring a custom {@link SignificanceHeuristic}.
  */
 public class CustomSignificanceHeuristicPlugin extends Plugin implements SearchPlugin {
+
+    /**
+     * Instantiate this plugin.
+     */
+    public CustomSignificanceHeuristicPlugin() {};
+
     @Override
     public List<SignificanceHeuristicSpec<?>> getSignificanceHeuristics() {
         return singletonList(new SignificanceHeuristicSpec<>(SimpleHeuristic.NAME, SimpleHeuristic::new, SimpleHeuristic.PARSER));

diff --git a/...ce-heuristic/src/main/java/org/opensearch/example/customsigheuristic/SimpleHeuristic.java b/...ce-heuristic/src/main/java/org/opensearch/example/customsigheuristic/SimpleHeuristic.java
@@ -44,13 +44,25 @@
  * A simple {@linkplain SignificanceHeuristic} used an example of declaring a custom heuristic.
  */
 public class SimpleHeuristic extends SignificanceHeuristic {
+    /**
+     * The name of this NamedWriteable heuristic.
+     */
     public static final String NAME = "simple";
+
+    /**
+     * The parser with which to deserialize this object from XContent.
+     */
     public static final ObjectParser<SimpleHeuristic, Void> PARSER = new ObjectParser<>(NAME, SimpleHeuristic::new);
 
+    /**
+     * Instantiates this object.
+     */
     public SimpleHeuristic() {}
 
     /**
      * Read from a stream.
+     *
+     * @param in Input to read the value from
      */
     public SimpleHeuristic(StreamInput in) throws IOException {
         // Nothing to read

diff --git a/...cance-heuristic/src/main/java/org/opensearch/example/customsigheuristic/package-info.java b/...cance-heuristic/src/main/java/org/opensearch/example/customsigheuristic/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.
+ */
+
+/**
+ * Example classes demonstrating the use of a custom significance heuristic.
+ */
+package org.opensearch.example.customsigheuristic;
diff --git a/...ustom-suggester/src/main/java/org/opensearch/example/customsuggester/CustomSuggester.java b/...ustom-suggester/src/main/java/org/opensearch/example/customsuggester/CustomSuggester.java
@@ -41,8 +41,16 @@
 import java.io.IOException;
 import java.util.Locale;
 
+/**
+ * A custom suggester supportiong suggestion-based search.
+ */
 public class CustomSuggester extends Suggester<CustomSuggestionContext> {
 
+    /**
+     * Instantiate this object.
+     */
+    public CustomSuggester() {}
+
     // This is a pretty dumb implementation which returns the original text + fieldName + custom config option + 12 or 123
     @Override
     public Suggest.Suggestion<? extends Suggest.Suggestion.Entry<? extends Suggest.Suggestion.Entry.Option>> innerExecute(

diff --git a/...suggester/src/main/java/org/opensearch/example/customsuggester/CustomSuggesterPlugin.java b/...suggester/src/main/java/org/opensearch/example/customsuggester/CustomSuggesterPlugin.java
@@ -38,7 +38,16 @@
 import java.util.Collections;
 import java.util.List;
 
+/**
+ * Plugin demonstrating custom suggestion-based search.
+ */
 public class CustomSuggesterPlugin extends Plugin implements SearchPlugin {
+
+    /**
+     * Instantiate this class.
+     */
+    public CustomSuggesterPlugin() {}
+
     @Override
     public List<SearchPlugin.SuggesterSpec<?>> getSuggesters() {
         return Collections.singletonList(