Improve the javadocs around features infrastructure (elastic#106292)

server/src/main/java/org/elasticsearch/features/FeatureService.java

@@ -20,7 +20,8 @@
 import java.util.Set;
 
 /**
- * Manages information on the features supported by nodes in the cluster
+ * Manages information on the features supported by nodes in the cluster.
+ * For more information, see {@link FeatureSpecification}.
  */
 public class FeatureService {
 
@@ -36,6 +37,10 @@ public class FeatureService {
     private final NavigableMap<Version, Set<String>> historicalFeatures;
     private final Map<String, NodeFeature> nodeFeatures;
 
+    /**
+     * Creates a new {@code FeatureService}, reporting all the features declared in {@code specs}
+     * as the local node's supported feature set
+     */
     public FeatureService(List<? extends FeatureSpecification> specs) {
 
         var featureData = FeatureData.createFromSpecifications(specs);
@@ -47,6 +52,7 @@ public FeatureService(List<? extends FeatureSpecification> specs) {
 
     /**
      * The non-historical features supported by this node.
+     * @return Map of {@code feature-id} to its declaring {@code NodeFeature} object.
      */
     public Map<String, NodeFeature> getNodeFeatures() {
         return nodeFeatures;

server/src/main/java/org/elasticsearch/features/FeatureSpecification.java

@@ -15,6 +15,17 @@
 
 /**
  * Specifies one or more features that are supported by this node.
+ * <p>
+ * Features are published as part of node information in cluster state.
+ * Code can check if all nodes in a cluster support a feature using {@link FeatureService#clusterHasFeature}.
+ * Once all nodes in a cluster support a feature, other nodes are blocked from joining that cluster
+ * unless they also support that feature (this is known as the 'feature ratchet').
+ * So once a feature is supported by a cluster, it will always be supported by that cluster in the future.
+ * <p>
+ * The feature information in cluster state should not normally be directly accessed.
+ * All feature checks should be done through {@code FeatureService} to ensure that Elasticsearch's
+ * guarantees on the introduction of new functionality are followed;
+ * that is, new functionality is not enabled until all nodes in the cluster support it.
  */
 public interface FeatureSpecification {
     /**
@@ -25,7 +36,8 @@ default Set<NodeFeature> getFeatures() {
     }
 
     /**
-     * Returns information on historical features that should be added to all nodes at or above the {@link Version} specified.
+     * Returns information on historical features that should be deemed to be present on all nodes
+     * on or above the {@link Version} specified.
      */
     default Map<NodeFeature, Version> getHistoricalFeatures() {
         return Map.of();