add comments

Signed-off-by: Poojita Raj <poojiraj@amazon.com>

server/src/main/java/org/opensearch/cluster/metadata/Metadata.java

@@ -110,6 +110,7 @@ public class Metadata implements Iterable<IndexMetadata>, Diffable<Metadata>, To
 
     /**
      * Utility to identify whether input index uses SEGMENT replication strategy in established cluster state metadata.
+     * Note: Method intended for use by other plugins as well.
      *
      * @param indexName Index name
      * @return true if index uses SEGMENT replication, false otherwise

server/src/main/java/org/opensearch/cluster/routing/RoutingNodes.java

@@ -366,6 +366,14 @@ public ShardRouting activePrimary(ShardId shardId) {
         return null;
     }
 
+    /**
+     * Returns one active replica shard for the given shard id or <code>null</code> if
+     * no active replica is found.
+     *
+     * Since replicas could possibly be on nodes with an older version of OpenSearch than
+     * the primary is, this will return replicas on the highest version of OpenSearch when document
+     * replication is enabled.
+     */
     public ShardRouting activeReplicaWithHighestVersion(ShardId shardId) {
         // It's possible for replicaNodeVersion to be null, when disassociating dead nodes
         // that have been removed, the shards are failed, and part of the shard failing
@@ -384,6 +392,15 @@ public ShardRouting activeReplicaWithHighestVersion(ShardId shardId) {
             .orElse(null);
     }
 
+    /**
+     * Returns one active replica shard for the given shard id or <code>null</code> if
+     * no active replica is found.
+     *
+     * Since replicas could possibly be on nodes with a higher version of OpenSearch than
+     * the primary is, this will return replicas on the oldest version of OpenSearch when segment
+     * replication is enabled to allow for replica to read segments from primary.
+     *
+     */
     public ShardRouting activeReplicaWithOldestVersion(ShardId shardId) {
         // It's possible for replicaNodeVersion to be null. Therefore, we need to protect against the version being null
         // (meaning the node will be going away).