Made the javadoc for getSegmentInfosSnapshot() better

Signed-off-by: Kartik Ganesh <[email protected]>

server/src/main/java/org/opensearch/index/engine/Engine.java

@@ -176,12 +176,14 @@ public final EngineConfig config() {
     protected abstract SegmentInfos getLatestSegmentInfos();
 
     /**
-     * Fetch a snapshot of the latest SegmentInfos from the engine. Using this method
-     * ensures that segment files are retained in the directory until the reference is closed.
+     * In contrast to {@link #getLatestSegmentInfos()}, which returns a {@link SegmentInfos}
+     * object directly, this method returns a {@link GatedCloseable} reference to the same object.
+     * This allows the engine to include a clean-up {@link org.opensearch.common.CheckedRunnable}
+     * which is run when the reference is closed. The default implementation of the clean-up
+     * procedure is a no-op.
      *
      * @return {@link GatedCloseable} - A wrapper around a {@link SegmentInfos} instance that
      * must be closed for segment files to be deleted.
-     * @throws EngineException - When segment infos cannot be safely retrieved
      */
     public GatedCloseable<SegmentInfos> getSegmentInfosSnapshot() {
         // default implementation

server/src/main/java/org/opensearch/index/engine/InternalEngine.java

@@ -2305,6 +2305,11 @@ public SegmentInfos getLatestSegmentInfos() {
         }
     }
 
+    /**
+     * Fetch the latest {@link SegmentInfos} object via {@link #getLatestSegmentInfos()}
+     * but also increment the ref-count to ensure that these segment files are retained
+     * until the reference is closed. On close, the ref-count is decremented.
+     */
     @Override
     public GatedCloseable<SegmentInfos> getSegmentInfosSnapshot() {
         final SegmentInfos segmentInfos = getLatestSegmentInfos();