LUCENE-5612: Add more documentation.

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

lucene/CHANGES.txt

@@ -330,6 +330,12 @@ Build
 * LUCENE-5614: Enable building on Java 8 using Apache Ant 1.8.3 or 1.8.4
   by adding a workaround for the Ant bug.  (Uwe Schindler)
 
+* LUCENE-5612: Add a new Ant target in lucene/core to test LockFactory
+  implementations: "ant test-lock-factory". By default it is ran
+  after the core testsuite on NativeFSLockFactory. To test another one,
+  pass -Dlock.factory.impl to Ant.  (Uwe Schindler, Mike McCandless,
+  Robert Muir)
+
 Documentation
 
 * LUCENE-5534: Add javadocs to GreekStemmer methods. 

lucene/core/build.xml

@@ -177,7 +177,8 @@
     </or>
   </condition>
   
-  <target name="test-lock-factory" depends="resolve-groovy,compile-core" unless="-ignore-test-lock-factory">
+  <target name="test-lock-factory" depends="resolve-groovy,compile-core" unless="-ignore-test-lock-factory"
+    description="Run LockStressTest with multiple JVMs">
     <property name="lockverifyserver.host" value="127.0.0.1"/>
     <property name="lock.factory.impl" value="org.apache.lucene.store.NativeFSLockFactory"/>
     <property name="lock.factory.dir" location="${build.dir}/lockfactorytest"/>

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

@@ -23,10 +23,21 @@ import java.io.IOException;
  * <p>Base class for Locking implementation.  {@link Directory} uses
  * instances of this class to implement locking.</p>
  *
- * <p>Note that there are some useful tools to verify that
- * your LockFactory is working correctly: {@link
- * VerifyingLockFactory}, {@link LockStressTest}, {@link
- * LockVerifyServer}.</p>
+ * <p>Lucene uses {@link NativeFSLockFactory} by default for
+ * {@link FSDirectory}-based index directories.</p>
+ *
+ * <p>Special care needs to be taken if you change the locking
+ * implementation: First be certain that no writer is in fact
+ * writing to the index otherwise you can easily corrupt
+ * your index. Be sure to do the LockFactory change on all Lucene
+ * instances and clean up all leftover lock files before starting
+ * the new configuration for the first time. Different implementations
+ * can not work together!</p>
+ *
+ * <p>If you suspect that some LockFactory implementation is
+ * not working properly in your environment, you can easily
+ * test it by using {@link VerifyingLockFactory}, {@link
+ * LockVerifyServer} and {@link LockStressTest}.</p>
  *
  * @see LockVerifyServer
  * @see LockStressTest

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

@@ -40,13 +40,22 @@ import org.apache.lucene.util.IOUtils;
  * could be left when the JVM exits abnormally.</p>
  *
  * <p>The primary benefit of {@link NativeFSLockFactory} is
- * that lock files will be properly removed (by the OS) if
- * the JVM has an abnormal exit.</p>
+ * that locks (not the lock file itsself) will be properly
+ * removed (by the OS) if the JVM has an abnormal exit.</p>
  * 
  * <p>Note that, unlike {@link SimpleFSLockFactory}, the existence of
- * leftover lock files in the filesystem on exiting the JVM
- * is fine because the OS will free the locks held against
- * these files even though the files still remain.</p>
+ * leftover lock files in the filesystem is fine because the OS
+ * will free the locks held against these files even though the
+ * files still remain. Lucene will never actively remove the lock
+ * files, so although you see them, the index may not be locked.</p>
+ *
+ * <p>Special care needs to be taken if you change the locking
+ * implementation: First be certain that no writer is in fact
+ * writing to the index otherwise you can easily corrupt
+ * your index. Be sure to do the LockFactory change on all Lucene
+ * instances and clean up all leftover lock files before starting
+ * the new configuration for the first time. Different implementations
+ * can not work together!</p>
  *
  * <p>If you suspect that this or any other LockFactory is
  * not working properly in your environment, you can easily

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

@@ -42,6 +42,14 @@ import java.io.IOException;
  * writing to the index otherwise you can easily corrupt
  * your index.</p>
  *
+ * <p>Special care needs to be taken if you change the locking
+ * implementation: First be certain that no writer is in fact
+ * writing to the index otherwise you can easily corrupt
+ * your index. Be sure to do the LockFactory change all Lucene
+ * instances and clean up all leftover lock files before starting
+ * the new configuration for the first time. Different implementations
+ * can not work together!</p>
+ *
  * <p>If you suspect that this or any other LockFactory is
  * not working properly in your environment, you can easily
  * test it by using {@link VerifyingLockFactory}, {@link