From 82533898f2108958714afe9c74e51db233814e85 Mon Sep 17 00:00:00 2001
From: Shai Erera <shaie@apache.org>
Date: Tue, 26 Jun 2012 07:26:44 +0000
Subject: [PATCH] LUCENE-4164: Improve IndexWriter.addIndexes(IndexReader)
 javadocs

git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/trunk@1353843 13f79535-47bb-0310-9956-ffa450edef68
---
 .../org/apache/lucene/index/IndexWriter.java  | 58 +++++++++++--------
 1 file changed, 35 insertions(+), 23 deletions(-)

diff --git a/lucene/core/src/java/org/apache/lucene/index/IndexWriter.java b/lucene/core/src/java/org/apache/lucene/index/IndexWriter.java
index 1729d92070f..30e8598a18b 100644
--- a/lucene/core/src/java/org/apache/lucene/index/IndexWriter.java
+++ b/lucene/core/src/java/org/apache/lucene/index/IndexWriter.java
@@ -2243,29 +2243,41 @@ public class IndexWriter implements Closeable, TwoPhaseCommit {
       handleOOM(oom, "addIndexes(Directory...)");
     }
   }
-
-  /** Merges the provided indexes into this index.
-   * <p>The provided IndexReaders are not closed.</p>
-   *
-   * <p><b>NOTE:</b> while this is running, any attempts to
-   * add or delete documents (with another thread) will be
-   * paused until this method completes.
-   *
-   * <p>See {@link #addIndexes} for details on transactional 
-   * semantics, temporary free space required in the Directory, 
-   * and non-CFS segments on an Exception.</p>
-   *
-   * <p><b>NOTE</b>: if this method hits an OutOfMemoryError
-   * you should immediately close the writer.  See <a
-   * href="#OOME">above</a> for details.</p>
-   *
-   * <p><b>NOTE</b>: if you call {@link #close(boolean)}
-   * with <tt>false</tt>, which aborts all running merges,
-   * then any thread still running this method might hit a
-   * {@link MergePolicy.MergeAbortedException}.
-   *
-   * @throws CorruptIndexException if the index is corrupt
-   * @throws IOException if there is a low-level IO error
+  
+  /**
+   * Merges the provided indexes into this index.
+   * 
+   * <p>
+   * The provided IndexReaders are not closed.
+   * 
+   * <p>
+   * See {@link #addIndexes} for details on transactional semantics, temporary
+   * free space required in the Directory, and non-CFS segments on an Exception.
+   * 
+   * <p>
+   * <b>NOTE</b>: if this method hits an OutOfMemoryError you should immediately
+   * close the writer. See <a href="#OOME">above</a> for details.
+   * 
+   * <p>
+   * <b>NOTE:</b> this method merges all given {@link IndexReader}s in one
+   * merge. If you intend to merge a large number of readers, it may be better
+   * to call this method multiple times, each time with a small set of readers.
+   * In principle, if you use a merge policy with a {@code mergeFactor} or
+   * {@code maxMergeAtOnce} parameter, you should pass that many readers in one
+   * call. Also, if the given readers are {@link DirectoryReader}s, they can be
+   * opened with {@code termIndexInterval=-1} to save RAM, since during merge
+   * the in-memory structure is not used. See
+   * {@link DirectoryReader#open(Directory, int)}.
+   * 
+   * <p>
+   * <b>NOTE</b>: if you call {@link #close(boolean)} with <tt>false</tt>, which
+   * aborts all running merges, then any thread still running this method might
+   * hit a {@link MergePolicy.MergeAbortedException}.
+   * 
+   * @throws CorruptIndexException
+   *           if the index is corrupt
+   * @throws IOException
+   *           if there is a low-level IO error
    */
   public void addIndexes(IndexReader... readers) throws CorruptIndexException, IOException {
     ensureOpen();