kvserver: improve documentation for non-ready nodes

This commit improves the comment over the `StorePool`'s
`isNodeReadyForRoutineReplicaTransfer` method by clarifying the distinction
between such non-ready nodes and "dead" nodes.

Release note: None

pkg/kv/kvserver/store_pool.go

@@ -350,10 +350,19 @@ type StorePool struct {
  nodeLocalities map[roachpb.NodeID]localityWithString
  }
 
- // isStoreReadyForRoutineReplicaTransfer returns true if the
- // store is live and thus a good candidate to receive a replica.
- // This is defined as a closure reference here instead
+ // isStoreReadyForRoutineReplicaTransfer returns true iff the store's node is
+ // live (as indicated by its `NodeLivenessStatus`) and thus a legal candidate
+ // to receive a replica. This is defined as a closure reference here instead
  // of a regular method so it can be overridden in tests.
+ //
+ // NB: What this method aims to capture is distinct from "dead" nodes. Nodes
+ // are classified as "dead" if they haven't successfully heartbeat their
+ // liveness record in the last `server.time_until_store_dead` seconds.
+ //
+ // Functionally, the distinction is that we simply avoid transferring replicas
+ // to "non-ready" nodes (i.e. nodes that _currently_ have a non-live
+ // `NodeLivenessStatus`), whereas we _actively move replicas off of "dead"
+ // nodes_.
  isStoreReadyForRoutineReplicaTransfer func(context.Context, roachpb.StoreID) bool
 }