Clarify JavaDoc for DiscoveryNodes#resolveNodes

server/src/main/java/org/elasticsearch/cluster/node/DiscoveryNodes.java

@@ -318,12 +318,19 @@ public DiscoveryNode resolveNode(String node) {
     }
 
     /**
-     * resolves a set of node "descriptions" to concrete and existing node ids. "descriptions" can be (resolved in this order):
-     * - "_local" or "_master" for the relevant nodes
-     * - a node id
-     * - a wild card pattern that will be matched against node names
-     * - a "attr:value" pattern, where attr can be a node role (master, data, ingest etc.) in which case the value can be true or false,
-     *   or a generic node attribute name in which case value will be treated as a wildcard and matched against the node attribute values.
+     * Resolves a set of nodes according to the given sequence of node specifications. Implements the logic in various APIs that allow the
+     * user to run the action on a subset of the nodes in the cluster. See [Node specification] in the reference manual for full details.
+     *
+     * Works by tracking the current set of nodes and applying each node specification in sequence. The set starts out empty and each node
+     * specification may either add or remove nodes. For instance:
+     *
+     * - _local, _master and _all respectively add to the subset the local node, the currently-elected master, and all the nodes
+     * - node IDs, names, hostnames and IP addresses all add to the subset any nodes which match
+     * - a wildcard-based pattern of the form "attr*:value*" adds to the subset all nodes with a matching attribute with a matching value
+     * - role:true adds to the subset all nodes with a matching role
+     * - role:false removes from the subset all nodes with a matching role.
+     *
+     * An empty sequence of node specifications returns all nodes, since the corresponding actions run on all nodes by default.
      */
     public String[] resolveNodes(String... nodes) {
         if (nodes == null || nodes.length == 0) {