svn commit: r1691892 - in /lucene/dev/trunk: ./ lucene/ lucene/core/ lucene/core/src/java/org/apache/lucene/store/IndexInput.java

[dw...@apache.org]

Author: dweiss
Date: Mon Jul 20 08:57:13 2015
New Revision: 1691892

URL: http://svn.apache.org/r1691892
Log:
LUCENE-6225: Clarify documentation of clone/close in IndexInput.

Modified:
    lucene/dev/trunk/   (props changed)
    lucene/dev/trunk/lucene/   (props changed)
    lucene/dev/trunk/lucene/core/   (props changed)
    lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/store/IndexInput.java

Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/store/IndexInput.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/store/IndexInput.java?rev=1691892&r1=1691891&r2=1691892&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/store/IndexInput.java (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/store/IndexInput.java Mon Jul 20 08:57:13 2015
@@ -20,19 +20,23 @@ package org.apache.lucene.store;
 import java.io.Closeable;
 import java.io.IOException;
 
-/** Abstract base class for input from a file in a {@link Directory}.  A
+/** 
+ * Abstract base class for input from a file in a {@link Directory}.  A
  * random-access input stream.  Used for all Lucene index input operations.
  *
  * <p>{@code IndexInput} may only be used from one thread, because it is not
  * thread safe (it keeps internal state like file position). To allow
  * multithreaded use, every {@code IndexInput} instance must be cloned before
- * used in another thread. Subclasses must therefore implement {@link #clone()},
+ * it is used in another thread. Subclasses must therefore implement {@link #clone()},
  * returning a new {@code IndexInput} which operates on the same underlying
- * resource, but positioned independently. Lucene never closes cloned
- * {@code IndexInput}s, it will only do this on the original one.
- * The original instance must take care that cloned instances throw
- * {@link AlreadyClosedException} when the original one is closed.
- 
+ * resource, but positioned independently. 
+ * 
+ * <p><b>Warning:</b> Lucene never closes cloned
+ * {@code IndexInput}s, it will only call {@link #close()} on the original object.
+ * 
+ * <p>If you access the cloned IndexInput after closing the original object,
+ * any <code>readXXX</code> methods will throw {@link AlreadyClosedException}.
+ *
  * @see Directory
  */
 public abstract class IndexInput extends DataInput implements Cloneable,Closeable {
@@ -73,10 +77,12 @@ public abstract class IndexInput extends
   }
   
   /** {@inheritDoc}
+   * 
    * <p><b>Warning:</b> Lucene never closes cloned
-   * {@code IndexInput}s, it will only do this on the original one.
-   * The original instance must take care that cloned instances throw
-   * {@link AlreadyClosedException} when the original one is closed.
+   * {@code IndexInput}s, it will only call {@link #close()} on the original object.
+   * 
+   * <p>If you access the cloned IndexInput after closing the original object,
+   * any <code>readXXX</code> methods will throw {@link AlreadyClosedException}.
    */
   @Override
   public IndexInput clone() {