Better explain Plugin (#20573)

Adds some javadoc with more explanation on how to extend Plugin and
why we have all these `@Deprecated public final` `onModule` methods.

Closes #20564

core/src/main/java/org/elasticsearch/plugins/Plugin.java

@@ -48,16 +48,22 @@
 import java.util.function.UnaryOperator;
 
 /**
- * An extension point allowing to plug in custom functionality.
- * <p>
- * Implement any of these interfaces to extend Elasticsearch:
+ * An extension point allowing to plug in custom functionality. This class has a number of extension points that are available to all
+ * plugins, in addition you can implement any of the following interfaces to further customize Elasticsearch:
  * <ul>
  * <li>{@link ActionPlugin}
  * <li>{@link AnalysisPlugin}
+ * <li>{@link ClusterPlugin}
+ * <li>{@link DiscoveryPlugin}
+ * <li>{@link IngestPlugin}
  * <li>{@link MapperPlugin}
+ * <li>{@link RepositoryPlugin}
  * <li>{@link ScriptPlugin}
  * <li>{@link SearchPlugin}
  * </ul>
+ * <p>In addition to extension points this class also declares some {@code @Deprecated} {@code public final void onModule} methods. These
+ * methods should cause any extensions of {@linkplain Plugin} that used the pre-5.x style extension syntax to fail to build and point the
+ * plugin author at the new extension syntax. We hope that these make the process of upgrading a plugin from 2.x to 5.x only mildly painful.
  */
 public abstract class Plugin {
 
@@ -141,7 +147,19 @@ public UnaryOperator<Map<String, MetaData.Custom>> getCustomMetaDataUpgrader() {
     }
 
     /**
-     * Old-style guice index level extension point.
+     * Provides the list of this plugin's custom thread pools, empty if
+     * none.
+     *
+     * @param settings the current settings
+     * @return executors builders for this plugin's custom thread pools
+     */
+    public List<ExecutorBuilder<?>> getExecutorBuilders(Settings settings) {
+        return Collections.emptyList();
+    }
+
+    /**
+     * Old-style guice index level extension point. {@code @Deprecated} and {@code final} to act as a signpost for plugin authors upgrading
+     * from 2.x.
      *
      * @deprecated use #onIndexModule instead
      */
@@ -150,53 +168,47 @@ public final void onModule(IndexModule indexModule) {}
 
 
     /**
-     * Old-style guice settings extension point.
+     * Old-style guice settings extension point. {@code @Deprecated} and {@code final} to act as a signpost for plugin authors upgrading
+     * from 2.x.
      *
      * @deprecated use #getSettings and #getSettingsFilter instead
      */
     @Deprecated
     public final void onModule(SettingsModule settingsModule) {}
 
     /**
-     * Old-style guice scripting extension point.
+     * Old-style guice scripting extension point. {@code @Deprecated} and {@code final} to act as a signpost for plugin authors upgrading
+     * from 2.x.
      *
      * @deprecated implement {@link ScriptPlugin} instead
      */
     @Deprecated
     public final void onModule(ScriptModule module) {}
 
     /**
-     * Old-style analysis extension point.
+     * Old-style analysis extension point. {@code @Deprecated} and {@code final} to act as a signpost for plugin authors upgrading
+     * from 2.x.
      *
      * @deprecated implement {@link AnalysisPlugin} instead
      */
     @Deprecated
     public final void onModule(AnalysisModule module) {}
 
     /**
-     * Old-style action extension point.
+     * Old-style action extension point. {@code @Deprecated} and {@code final} to act as a signpost for plugin authors upgrading
+     * from 2.x.
      *
      * @deprecated implement {@link ActionPlugin} instead
      */
     @Deprecated
     public final void onModule(ActionModule module) {}
 
     /**
-     * Old-style action extension point.
+     * Old-style action extension point. {@code @Deprecated} and {@code final} to act as a signpost for plugin authors upgrading
+     * from 2.x.
      *
      * @deprecated implement {@link SearchPlugin} instead
      */
     @Deprecated
     public final void onModule(SearchModule module) {}
-
-    /**
-     * Provides the list of this plugin's custom thread pools, empty if
-     * none.
-     *
-     * @param settings the current settings
-     * @return executors builders for this plugin's custom thread pools
-     */
-    public List<ExecutorBuilder<?>> getExecutorBuilders(Settings settings) {
-        return Collections.emptyList();
-    }
 }