javadoc improvements

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

src/java/org/apache/lucene/index/IndexReader.java

@@ -44,6 +44,9 @@ import java.util.Set;
  document in the index.  These document numbers are ephemeral--they may change
  as documents are added to and deleted from an index.  Clients should thus not
  rely on a given document having the same number between sessions.
+ 
+ <p> An IndexReader can be opened on a directory for which an IndexWriter is
+ opened already, but it cannot be used to delete documents from the index then.
 
  @author Doug Cutting
  @version $Id$

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

@@ -44,9 +44,14 @@ import org.apache.lucene.analysis.Analyzer;
   href="#addDocument(org.apache.lucene.document.Document)"><b>addDocument</b></a> method.  
   When finished adding documents, <a href="#close()"><b>close</b></a> should be called.
 
-  If an index will not have more documents added for a while and optimal search
+  <p>If an index will not have more documents added for a while and optimal search
   performance is desired, then the <a href="#optimize()"><b>optimize</b></a>
   method should be called before the index is closed.
+  
+  <p>Opening an IndexWriter creates a lock file for the directory in use. Trying to open
+  another IndexWriter on the same directory will lead to an IOException. The IOException
+  is also thrown if an IndexReader on the same directory is used to delete documents
+  from the index.
   */
 
 public class IndexWriter {