Clarify intent of deprecation issue levels

x-pack/plugin/core/src/main/java/org/elasticsearch/xpack/core/deprecation/DeprecationIssue.java

@@ -23,10 +23,22 @@
  */
 public class DeprecationIssue implements Writeable, ToXContentObject {
 
+    /**
+     * Indicates the level of the deprecation warning.
+     */
     public enum Level implements Writeable {
-        NONE,
+        /**
+         * No action required in the cluster itself, but it is advised to read about the change, and may require making application changes.
+         */
         INFO,
+        /**
+         * Resolving this issue is advised but not required to upgrade. There may be undesired changes in behavior unless this issue is
+         * resolved before upgrading.
+         */
         WARNING,
+        /**
+         * This issue must be resolved to upgrade. Failures will occur unless this is resolved before upgrading.
+         */
         CRITICAL
         ;
 

x-pack/plugin/deprecation/src/main/java/org/elasticsearch/xpack/deprecation/ClusterDeprecationChecks.java

@@ -10,6 +10,9 @@
 import org.elasticsearch.cluster.metadata.MetaData;
 import org.elasticsearch.xpack.core.deprecation.DeprecationIssue;
 
+/**
+ * Cluster-level deprecation checks.
+ */
 public class ClusterDeprecationChecks {
 
     static DeprecationIssue checkShardLimit(ClusterState state) {