diff --git a/core/src/main/java/org/elasticsearch/plugins/Plugin.java b/core/src/main/java/org/elasticsearch/plugins/Plugin.java
index 1c79986e18f27..180c8efd73096 100644
--- a/core/src/main/java/org/elasticsearch/plugins/Plugin.java
+++ b/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.
- *
- * 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:
*
* - {@link ActionPlugin}
*
- {@link AnalysisPlugin}
+ *
- {@link ClusterPlugin}
+ *
- {@link DiscoveryPlugin}
+ *
- {@link IngestPlugin}
*
- {@link MapperPlugin}
+ *
- {@link RepositoryPlugin}
*
- {@link ScriptPlugin}
*
- {@link SearchPlugin}
*
+ * 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