Clarify intent of Accountable#ramBytesUsed

lucene/CHANGES.txt

@@ -312,6 +312,8 @@ Improvements
 * GITHUB#15989: DocValuesRangeIterator always tries to use skipper-based block iteration
   as its approximation. (Alan Woodward)
 
+* GITHUB#16000: Clarify that Accountable#ramBytesUsed() reports JVM heap memory only. (Luca Cavanna)
+
 Optimizations
 ---------------------
 * GITHUB#15861: Optimise PhraseScorer by short circuiting non competitive documents in TOP_SCORES mode. (Prithvi S)

lucene/core/src/java/org/apache/lucene/util/Accountable.java

@@ -20,13 +20,23 @@
 import java.util.Collections;
 
 /**
- * An object whose RAM usage can be computed.
+ * An object whose JVM heap memory usage can be computed.
+ *
+ * <p>Implementations should only account for memory allocated on the Java heap (i.e. memory managed
+ * by the JVM garbage collector). Off-heap resources such as memory-mapped files or native direct
+ * buffers should not be included; those should be tracked separately if needed (see e.g. {@link
+ * org.apache.lucene.codecs.KnnVectorsReader#getOffHeapByteSize}).
  *
  * @lucene.internal
  */
 public interface Accountable {
 
-  /** Return the memory usage of this object in bytes. Negative values are illegal. */
+  /**
+   * Returns an estimate of the JVM heap memory used by this object in bytes. The method name uses
+   * "ram" for historical reasons; only JVM heap memory should be reported. Off-heap resources such
+   * as memory-mapped files or native direct buffers should not be included. Negative values are
+   * illegal.
+   */
   long ramBytesUsed();
 
   /**