Improve documentation a bit.

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

lucene/core/src/java/org/apache/lucene/store/FSDirectory.java

@@ -24,6 +24,7 @@ import java.nio.file.DirectoryStream;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.StandardCopyOption;
+import java.nio.channels.ClosedChannelException; // javadoc @link
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.List;
@@ -41,14 +42,14 @@ import org.apache.lucene.util.IOUtils;
  *
  * <ul>
  *
- *  <li> {@link SimpleFSDirectory} is a straightforward
+ *  <li>{@link SimpleFSDirectory} is a straightforward
  *       implementation using Files.newByteChannel.
  *       However, it has poor concurrent performance
  *       (multiple threads will bottleneck) as it
  *       synchronizes when multiple threads read from the
  *       same file.
  *
- *  <li> {@link NIOFSDirectory} uses java.nio's
+ *  <li>{@link NIOFSDirectory} uses java.nio's
  *       FileChannel's positional io when reading to avoid
  *       synchronization when reading from the same file.
  *       Unfortunately, due to a Windows-only <a
@@ -60,9 +61,7 @@ import org.apache.lucene.util.IOUtils;
  *       {@code RAFDirectory} instead. See {@link NIOFSDirectory} java doc
  *       for details.
  *        
- *        
- *
- *  <li> {@link MMapDirectory} uses memory-mapped IO when
+ *  <li>{@link MMapDirectory} uses memory-mapped IO when
  *       reading. This is a good choice if you have plenty
  *       of virtual memory relative to your index size, eg
  *       if you are running on a 64 bit JRE, or you are
@@ -86,14 +85,9 @@ import org.apache.lucene.util.IOUtils;
  *       an important limitation to be aware of. This class supplies a
  *       (possibly dangerous) workaround mentioned in the bug report,
  *       which may fail on non-Sun JVMs.
- *       
- *       Applications using {@link Thread#interrupt()} or
- *       {@link Future#cancel(boolean)} should use
- *       {@code RAFDirectory} instead. See {@link MMapDirectory}
- *       java doc for details.
  * </ul>
  *
- * Unfortunately, because of system peculiarities, there is
+ * <p>Unfortunately, because of system peculiarities, there is
  * no single overall best implementation.  Therefore, we've
  * added the {@link #open} method, to allow Lucene to choose
  * the best FSDirectory implementation given your
@@ -103,6 +97,15 @@ import org.apache.lucene.util.IOUtils;
  * #open}.  For all others, you should instantiate the
  * desired implementation directly.
  *
+ * <p><b>NOTE:</b> Accessing one of the above subclasses either directly or
+ * indirectly from a thread while it's interrupted can close the
+ * underlying channel immediately if at the same time the thread is
+ * blocked on IO. The channel will remain closed and subsequent access
+ * to the index will throw a {@link ClosedChannelException}.
+ * Applications using {@link Thread#interrupt()} or
+ * {@link Future#cancel(boolean)} should use the slower legacy
+ * {@code RAFDirectory} from the {@code misc} Lucene module instead.
+ *
  * <p>The locking implementation is by default {@link
  * NativeFSLockFactory}, but can be changed by
  * passing in a custom {@link LockFactory} instance.
@@ -131,7 +134,7 @@ public abstract class FSDirectory extends BaseDirectory {
    *  The directory returned uses the {@link NativeFSLockFactory}.
    *  The directory is created at the named location if it does not yet exist.
    *
-   *  <p>Currently this returns {@link MMapDirectory} for most Solaris
+   *  <p>Currently this returns {@link MMapDirectory} for Linux, MacOSX, Solaris,
    *  and Windows 64-bit JREs, {@link NIOFSDirectory} for other
    *  non-Windows JREs, and {@link SimpleFSDirectory} for other
    *  JREs on Windows. It is highly recommended that you consult the

lucene/core/src/java/org/apache/lucene/store/MMapDirectory.java

@@ -28,6 +28,7 @@ import java.security.AccessController;
 import java.security.PrivilegedExceptionAction;
 import java.security.PrivilegedActionException;
 import java.util.Locale;
+import java.util.concurrent.Future;
 import java.lang.reflect.Method;
 
 import org.apache.lucene.store.ByteBufferIndexInput.BufferCleaner;
@@ -66,15 +67,19 @@ import org.apache.lucene.util.Constants;
  * <p>This class supplies the workaround mentioned in the bug report
  * (see {@link #setUseUnmap}), which may fail on
  * non-Sun JVMs. It forcefully unmaps the buffer on close by using
- * an undocumented internal cleanup functionality.
- * {@link #UNMAP_SUPPORTED} is <code>true</code>, if the workaround
- * can be enabled (with no guarantees).
+ * an undocumented internal cleanup functionality. If
+ * {@link #UNMAP_SUPPORTED} is <code>true</code>, the workaround
+ * will be automatically enabled (with no guarantees; if you discover
+ * any problems, you can disable it).
  * <p>
  * <b>NOTE:</b> Accessing this class either directly or
  * indirectly from a thread while it's interrupted can close the
  * underlying channel immediately if at the same time the thread is
  * blocked on IO. The channel will remain closed and subsequent access
- * to {@link MMapDirectory} will throw a {@link ClosedChannelException}. 
+ * to {@link MMapDirectory} will throw a {@link ClosedChannelException}. If
+ * your application uses either {@link Thread#interrupt()} or
+ * {@link Future#cancel(boolean)} you should use the legacy {@code RAFDirectory}
+ * from the Lucene {@code misc} module in favor of {@link MMapDirectory}.
  * </p>
  * @see <a href="http://blog.thetaphi.de/2012/07/use-lucenes-mmapdirectory-on-64bit.html">Blog post about MMapDirectory</a>
  */

lucene/core/src/java/org/apache/lucene/store/NIOFSDirectory.java

@@ -47,8 +47,8 @@ import java.util.concurrent.Future; // javadoc
  * blocked on IO. The file descriptor will remain closed and subsequent access
  * to {@link NIOFSDirectory} will throw a {@link ClosedChannelException}. If
  * your application uses either {@link Thread#interrupt()} or
- * {@link Future#cancel(boolean)} you should use {@code RAFDirectory} in
- * favor of {@link NIOFSDirectory}.
+ * {@link Future#cancel(boolean)} you should use the legacy {@code RAFDirectory}
+ * from the Lucene {@code misc} module in favor of {@link NIOFSDirectory}.
  * </p>
  */
 public class NIOFSDirectory extends FSDirectory {

lucene/core/src/java/org/apache/lucene/store/SimpleFSDirectory.java

@@ -21,9 +21,11 @@ import java.io.EOFException;
 import java.io.IOException;
 import java.nio.ByteBuffer;
 import java.nio.channels.SeekableByteChannel;
+import java.nio.channels.ClosedChannelException; // javadoc @link
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.StandardOpenOption;
+import java.util.concurrent.Future;
 
 /** A straightforward implementation of {@link FSDirectory}
  *  using {@link Files#newByteChannel(Path, java.nio.file.OpenOption...)}.  
@@ -31,7 +33,18 @@ import java.nio.file.StandardOpenOption;
  *  poor concurrent performance (multiple threads will
  *  bottleneck) as it synchronizes when multiple threads
  *  read from the same file.  It's usually better to use
- *  {@link NIOFSDirectory} or {@link MMapDirectory} instead. */
+ *  {@link NIOFSDirectory} or {@link MMapDirectory} instead.
+ * <p>
+ * <b>NOTE:</b> Accessing this class either directly or
+ * indirectly from a thread while it's interrupted can close the
+ * underlying file descriptor immediately if at the same time the thread is
+ * blocked on IO. The file descriptor will remain closed and subsequent access
+ * to {@link SimpleFSDirectory} will throw a {@link ClosedChannelException}. If
+ * your application uses either {@link Thread#interrupt()} or
+ * {@link Future#cancel(boolean)} you should use the legacy {@code RAFDirectory}
+ * from the Lucene {@code misc} module in favor of {@link SimpleFSDirectory}.
+ * </p>
+ */
 public class SimpleFSDirectory extends FSDirectory {
     
   /** Create a new SimpleFSDirectory for the named location.