[DOCS] Clarify diff between shards per node settings (#64875) (#65071)

Clarifies differences between the
`cluster.routing.allocation.total_shards_per_node` and
`cluster.max_shards_per_node` cluster settings.

Closes #51839

Co-authored-by: Gordon Brown <arcsech@gmail.com>

docs/reference/index-modules/allocation/total_shards.asciidoc

@@ -17,10 +17,25 @@ number of shards from a single index allowed per node:
 
 You can also limit the amount of shards a node can have regardless of the index:
 
+[[cluster-total-shards-per-node]]
 `cluster.routing.allocation.total_shards_per_node`::
++
+--
+(<<dynamic-cluster-setting,Dynamic>>)
+Maximum number of primary and replica shards allocated to each node. Defaults to
+`-1` (unlimited).
 
-    The maximum number of shards (replicas and primaries) that will be
+{es} checks this setting during shard allocation. For example, a cluster has a
-    allocated to a single node globally.  Defaults to unbounded (-1).
+`cluster.routing.allocation.total_shards_per_node` setting of `100` and three
+nodes with the following shard allocations:
+
+- Node A: 100 shards
+- Node B: 98 shards
+- Node C: 1 shard
+
+If node C fails, {es} reallocates its shard to node B. Reallocating the shard to
+node A would exceed node A's shard limit.
+--
 
 [WARNING]
 =======================================

docs/reference/modules/cluster/misc.asciidoc

@@ -53,16 +53,29 @@ Closed indices do not contribute to the shard count.
 
 You can dynamically adjust the cluster shard limit with the following setting:
 
+[[cluster-max-shards-per-node]]
 `cluster.max_shards_per_node`::
-     (<<dynamic-cluster-setting,Dynamic>>)
++
-     Controls the number of shards allowed in the cluster per data node.
+--
+(<<dynamic-cluster-setting,Dynamic>>)
+Limits the total number of primary and replica shards for the cluster. {es}
+calculates the limit as follows:
 
-With the default setting, a 3-node cluster allows 3,000 shards total, across all open indexes. 
+`cluster.max_shards_per_node * number of data nodes`
-If you reduce the limit to 500, the cluster would allow 1,500 shards total.
 
-NOTE: If there are no data nodes in the cluster, the limit will not be enforced.
+Shards for closed indices do not count toward this limit. Defaults to `1000`.
-This allows the creation of indices during cluster creation if dedicated master
+A cluster with no data nodes is unlimited.
-nodes are set up before data nodes.
+
+{es} rejects any request that creates more shards than this limit allows. For
+example, a cluster with a `cluster.max_shards_per_node` setting of `100` and
+three data nodes has a shard limit of 300. If the cluster already contains 296
+shards, {es} rejects any request that adds five or more shards to the cluster.
+
+NOTE: This setting does not limit shards for individual nodes. To limit the
+number of shards for each node, use the
+<<cluster-total-shards-per-node,`cluster.routing.allocation.total_shards_per_node`>>
+setting.
+--
 
 [[user-defined-data]]
 ===== User-defined cluster metadata