LUCENE-4876: Add more notes about IndexWriterConfig.clone and its implications.

git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/trunk@1494146 13f79535-47bb-0310-9956-ffa450edef68

lucene/core/src/java/org/apache/lucene/index/IndexDeletionPolicy.java

@@ -20,6 +20,8 @@ package org.apache.lucene.index;
 import java.util.List;
 import java.io.IOException;
 
+import org.apache.lucene.store.Directory;
+
 /**
  * <p>Expert: policy for deletion of stale {@link IndexCommit index commits}. 
  * 
@@ -46,6 +48,10 @@ import java.io.IOException;
  * target="top"
  * href="http://issues.apache.org/jira/browse/LUCENE-710">LUCENE-710</a>
  * for details.</p>
+ *
+ * <p>Implementers of sub-classes should make sure that {@link #clone()}
+ * returns an independent instance able to work with any other {@link IndexWriter}
+ * or {@link Directory} instance.</p>
  */
 
 public abstract class IndexDeletionPolicy implements Cloneable {

lucene/core/src/java/org/apache/lucene/index/IndexWriter.java

@@ -631,7 +631,12 @@ public class IndexWriter implements Closeable, TwoPhaseCommit {
   /**
    * Constructs a new IndexWriter per the settings given in <code>conf</code>.
    * Note that the passed in {@link IndexWriterConfig} is
-   * privately cloned; if you need to make subsequent "live"
+   * privately cloned, which, in-turn, clones the
+   * {@link IndexWriterConfig#getFlushPolicy() flush policy},
+   * {@link IndexWriterConfig#getIndexDeletionPolicy() deletion policy},
+   * {@link IndexWriterConfig#getMergePolicy() merge policy},
+   * and {@link IndexWriterConfig#getMergeScheduler() merge scheduler}.
+   * If you need to make subsequent "live"
    * changes to the configuration use {@link #getConfig}.
    * <p>
    * 

lucene/core/src/java/org/apache/lucene/index/MergeScheduler.java

@@ -24,7 +24,9 @@ import java.io.IOException;
  *  implementing this interface to execute the merges
  *  selected by a {@link MergePolicy}.  The default
  *  MergeScheduler is {@link ConcurrentMergeScheduler}.</p>
- *
+ *  <p>Implementers of sub-classes should make sure that {@link #clone()}
+ *  returns an independent instance able to work with any {@link IndexWriter}
+ *  instance.</p>
  * @lucene.experimental
 */
 public abstract class MergeScheduler implements Closeable, Cloneable {