Index: lucene/core/src/java/org/apache/lucene/store/RAMDirectory.java
===================================================================
--- lucene/core/src/java/org/apache/lucene/store/RAMDirectory.java	(revision 1305791)
+++ lucene/core/src/java/org/apache/lucene/store/RAMDirectory.java	(working copy)
@@ -34,6 +34,18 @@
  * A memory-resident {@link Directory} implementation.  Locking
  * implementation is by default the {@link SingleInstanceLockFactory}
  * but can be changed with {@link #setLockFactory}.
+ * 
+ * <p><b>Warning:</b> This class is not intended to work with huge
+ * indexes. Everything beyond several hundred megabytes will waste
+ * resources (GC cycles), because it uses an internal buffer size
+ * of 1024 bytes, producing millions of {@code byte[1024]} arrays.
+ * This class is optimized for small memory-resident indexes.
+ * It also has bad concurrency on multithreaded environments.
+ * 
+ * <p>It is recommended to materialize large indexes on disk and use
+ * {@link MMapDirectory}, which is a high-performance directory
+ * implementation working directly on the file system cache of the
+ * operating system, so copying data to Java heap space is not useful.
  */
 public class RAMDirectory extends Directory implements Serializable {
 
@@ -59,10 +71,20 @@
    * Creates a new <code>RAMDirectory</code> instance from a different
    * <code>Directory</code> implementation.  This can be used to load
    * a disk-based index into memory.
-   * <P>
-   * This should be used only with indices that can fit into memory.
-   * <P>
-   * Note that the resulting <code>RAMDirectory</code> instance is fully
+   * 
+   * <p><b>Warning:</b> This class is not intended to work with huge
+   * indexes. Everything beyond several hundred megabytes will waste
+   * resources (GC cycles), because it uses an internal buffer size
+   * of 1024 bytes, producing millions of {@code byte[1024]} arrays.
+   * This class is optimized for small memory-resident indexes.
+   * It also has bad concurrency on multithreaded environments.
+   * 
+   * <p>For disk-based indexes it is recommended to use
+   * {@link MMapDirectory}, which is a high-performance directory
+   * implementation working directly on the file system cache of the
+   * operating system, so copying data to Java heap space is not useful.
+   * 
+   * <p>Note that the resulting <code>RAMDirectory</code> instance is fully
    * independent from the original <code>Directory</code> (it is a
    * complete copy).  Any subsequent changes to the
    * original <code>Directory</code> will not be visible in the