Improve ShardRoutingState docs (#126875)

Author: DiannaHohensee

server/src/main/java/org/elasticsearch/cluster/routing/ShardRoutingState.java

@@ -10,25 +10,38 @@
 package org.elasticsearch.cluster.routing;
 
 /**
- * Represents the current state of a {@link ShardRouting} as defined by the
- * cluster.
+ * Tracks the current assignment status of a particular shard copy ({@link ShardRouting}).
  */
 public enum ShardRoutingState {
     /**
-     * The shard is not assigned to any node.
+     * The shard is not assigned to any node; any data which it contains is unavailable to the cluster.
+     * <p>
+     * A shard transitions from {@link #UNASSIGNED} to {@link #INITIALIZING} when the master wants an assigned data node to create or start
+     * recovering that shard copy. A shard may also transition back to {@link #UNASSIGNED} in case of any failure, during initialization or
+     * later.
      */
     UNASSIGNED((byte) 1),
+
     /**
-     * The shard is initializing (probably recovering from either a peer shard
-     * or gateway).
+     * The shard is assigned to a node and the recovery process has begun. The shard data is not yet available on the node initializing the
+     * shard (though there is a small window of time when the data is available, after recovery completes and before the cluster state is
+     * updated to mark the shard {@link #STARTED}).
+     * <p>
+     * A shard transitions from {@link #INITIALIZING} -> {@link #STARTED} when recovery is complete and the data node informs the master
+     * that it is ready to serve requests.
      */
     INITIALIZING((byte) 2),
+
     /**
-     * The shard is started.
+     * The shard is assigned to a specific data node and ready to accept indexing and search requests.
+     * <p>
+     * A shard transitions from {@link #STARTED} -> {@link #RELOCATING} when the master wants to initialize the shard elsewhere.
      */
     STARTED((byte) 3),
+
     /**
-     * The shard is in the process being relocated.
+     * The shard is being reassigned away from one node to another node. This is the state of the shard on a source node when the shard is
+     * being moved away to a new target node. The target shard copy will be {@link #INITIALIZING}.
      */
     RELOCATING((byte) 4);