Small fixes to clear voting config excls API (#87828)

Fixes the name of the REST param in the error message, and expands the
API docs to emphasise that the exclusions should be empty in normal
operation.

docs/changelog/87828.yaml

@@ -0,0 +1,5 @@
+pr: 87828
+summary: Small fixes to clear voting config excls API
+area: Cluster Coordination
+type: bug
+issues: []

docs/reference/cluster/voting-exclusions.asciidoc

@@ -34,16 +34,25 @@ and you remove fewer than half of the master-eligible nodes in the cluster at
 once, the <<modules-discovery-voting,voting configuration>> automatically
 shrinks.
 
-If you want to shrink the voting configuration to contain fewer than three nodes
-or to remove half or more of the master-eligible nodes in the cluster at once,
-you must use this API to remove departed nodes from the voting configuration
-manually. It adds an entry for that node in the voting configuration exclusions
-list. The cluster then tries to reconfigure the voting configuration to remove
-that node and to prevent it from returning.
+If you want to shrink the voting configuration to contain fewer than three
+nodes or to remove half or more of the master-eligible nodes in the cluster at
+once, use this API to remove departing nodes from the voting configuration
+manually. The API adds an entry for each specified node to the cluster's voting
+configuration exclusions list. It then waits until the cluster has reconfigured
+its voting configuration to exclude the specified nodes.
+
+Clusters should have no voting configuration exclusions in normal operation.
+Once the excluded nodes have stopped, clear the voting configuration exclusions
+with `DELETE /_cluster/voting_config_exclusions`. This API waits for the nodes
+to be fully removed from the cluster before it returns. If your cluster has
+voting configuration exclusions for nodes that you no longer intend to remove,
+use `DELETE /_cluster/voting_config_exclusions?wait_for_removal=false` to clear
+the voting configuration exclusions without waiting for the nodes to leave the
+cluster.
 
 If the API fails, you can safely retry it. Only a successful response
-guarantees that the node has been removed from the voting configuration and will
-not be reinstated.
+guarantees that the node has been removed from the voting configuration and
+will not be reinstated.
 
 NOTE: Voting exclusions are required only when you remove at least half of the
 master-eligible nodes from a cluster in a short time period. They are not

server/src/main/java/org/elasticsearch/action/admin/cluster/configuration/TransportClearVotingConfigExclusionsAction.java

@@ -112,7 +112,7 @@ public class TransportClearVotingConfigExclusionsAction extends TransportMasterN
                 public void onTimeout(TimeValue timeout) {
                     listener.onFailure(
                         new ElasticsearchTimeoutException(
-                            "timed out waiting for removal of nodes; if nodes should not be removed, set waitForRemoval to false. "
+                            "timed out waiting for removal of nodes; if nodes should not be removed, set ?wait_for_removal=false. "
                                 + initialState.getVotingConfigExclusions()
                         )
                     );

server/src/test/java/org/elasticsearch/action/admin/cluster/configuration/TransportClearVotingConfigExclusionsActionTests.java

@@ -160,7 +160,7 @@ public class TransportClearVotingConfigExclusionsActionTests extends ESTestCase
         assertThat(rootCause, instanceOf(ElasticsearchTimeoutException.class));
         assertThat(
             rootCause.getMessage(),
-            startsWith("timed out waiting for removal of nodes; if nodes should not be removed, set waitForRemoval to false. [")
+            startsWith("timed out waiting for removal of nodes; if nodes should not be removed, set ?wait_for_removal=false. [")
         );
     }