LUCENE-1670: improve javadocs

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

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

@@ -46,28 +46,24 @@ import java.util.Map;
 /**
   An <code>IndexWriter</code> creates and maintains an index.
 
-  <p>The <code>create</code> argument to the 
-  <a href="#IndexWriter(org.apache.lucene.store.Directory, org.apache.lucene.analysis.Analyzer, boolean)"><b>constructor</b></a>
-  determines whether a new index is created, or whether an existing index is
-  opened.  Note that you
-  can open an index with <code>create=true</code> even while readers are
-  using the index.  The old readers will continue to search
-  the "point in time" snapshot they had opened, and won't
-  see the newly created index until they re-open.  There are
-  also <a href="#IndexWriter(org.apache.lucene.store.Directory, org.apache.lucene.analysis.Analyzer)"><b>constructors</b></a>
-  with no <code>create</code> argument which
-  will create a new index if there is not already an index at the
-  provided path and otherwise open the existing index.</p>
+  <p>The <code>create</code> argument to the {@link
+  #IndexWriter(Directory, Analyzer, boolean) constructor} determines 
+  whether a new index is created, or whether an existing index is
+  opened.  Note that you can open an index with <code>create=true</code>
+  even while readers are using the index.  The old readers will 
+  continue to search the "point in time" snapshot they had opened, 
+  and won't see the newly created index until they re-open.  There are
+  also {@link #IndexWriter(Directory, Analyzer) constructors}
+  with no <code>create</code> argument which will create a new index
+  if there is not already an index at the provided path and otherwise 
+  open the existing index.</p>
 
-  <p>In either case, documents are added with <a
-  href="#addDocument(org.apache.lucene.document.Document)"><b>addDocument</b></a>
-  and removed with <a
-  href="#deleteDocuments(org.apache.lucene.index.Term)"><b>deleteDocuments(Term)</b></a>
-  or <a
-  href="#deleteDocuments(org.apache.lucene.search.Query)"><b>deleteDocuments(Query)</b></a>.
-  A document can be updated with <a href="#updateDocument(org.apache.lucene.index.Term, org.apache.lucene.document.Document)"><b>updateDocument</b></a> 
-  (which just deletes and then adds the entire document).
-  When finished adding, deleting and updating documents, <a href="#close()"><b>close</b></a> should be called.</p>
+  <p>In either case, documents are added with {@link #addDocument(Document)
+  addDocument} and removed with {@link #deleteDocuments(Term)} or {@link
+  #deleteDocuments(Query)}. A document can be updated with {@link
+  #updateDocument(Term, Document) updateDocument} (which just deletes
+  and then adds the entire document). When finished adding, deleting 
+  and updating documents, {@link #close() close} should be called.</p>
 
   <a name="flush"></a>
   <p>These changes are buffered in memory and periodically
@@ -90,23 +86,20 @@ import java.util.Map;
   for changing the {@link MergeScheduler}).</p>
 
   <a name="autoCommit"></a>
-  <p>The optional <code>autoCommit</code> argument to the <a
-  href="#IndexWriter(org.apache.lucene.store.Directory,
-  boolean,
-  org.apache.lucene.analysis.Analyzer)"><b>constructors</b></a>
+  <p>The optional <code>autoCommit</code> argument to the {@link
+  #IndexWriter(Directory, boolean, Analyzer) constructors}
   controls visibility of the changes to {@link IndexReader}
   instances reading the same index.  When this is
   <code>false</code>, changes are not visible until {@link
   #close()} or {@link #commit()} is called.  Note that changes will still be
-  flushed to the {@link org.apache.lucene.store.Directory}
-  as new files, but are not committed (no new
-  <code>segments_N</code> file is written referencing the
-  new files, nor are the files sync'd to stable storage)
+  flushed to the {@link Directory} as new files, but are 
+  not committed (no new <code>segments_N</code> file is written 
+  referencing the new files, nor are the files sync'd to stable storage)
   until {@link #close()} or {@link #commit()} is called.  If something
   goes terribly wrong (for example the JVM crashes), then
   the index will reflect none of the changes made since the
   last commit, or the starting state if commit was not called.
-  You can also call {@link #rollback}, which closes the writer
+  You can also call {@link #rollback()}, which closes the writer
   without committing any changes, and removes any index
   files that had been flushed but are now unreferenced.
   This mode is useful for preventing readers from refreshing
@@ -142,7 +135,7 @@ import java.util.Map;
   are not visible until the reader is re-opened.</p>
 
   <p>If an index will not have more documents added for a while and optimal search
-  performance is desired, then either the full <a href="#optimize()"><b>optimize</b></a>
+  performance is desired, then either the full {@link #optimize() optimize}
   method or partial {@link #optimize(int)} method should be
   called before the index is closed.</p>
 

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

@@ -22,9 +22,12 @@ import java.util.Set;
 
 /** <p>This class implements a {@link MergePolicy} that tries
  *  to merge segments into levels of exponentially
- *  increasing size, where each level has < mergeFactor
- *  segments in it.  Whenever a given levle has mergeFactor
- *  segments or more in it, they will be merged.</p>
+ *  increasing size, where each level has fewer segments than
+ *  the value of the merge factor. Whenever extra segments
+ *  (beyond the merge factor upper bound) are encountered,
+ *  all segments within the level are merged. You can get or
+ *  set the merge factor using {@link #getMergeFactor()} and
+ *  {@link #setMergeFactor(int)} respectively.</p>
  *
  * <p>This class is abstract and requires a subclass to
  * define the {@link #size} method which specifies how a

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

@@ -55,7 +55,7 @@ import java.util.Set;
  * (subject to change suddenly in the next release)</p>
  *
  * <p><b>NOTE</b>: This class typically requires access to
- * package-private APIs (eg, SegmentInfos) to do its job;
+ * package-private APIs (e.g. {@link SegmentInfo}s) to do its job;
  * if you implement your own MergePolicy, you'll need to put
  * it in package org.apache.lucene.index in order to use
  * these APIs.

src/java/org/apache/lucene/store/IndexOutput.java

@@ -162,6 +162,7 @@ public abstract class IndexOutput {
 
   /** Copy numBytes bytes from input to ourself. */
   public void copyBytes(IndexInput input, long numBytes) throws IOException {
+    assert numBytes >= 0: "numBytes=" + numBytes;
     long left = numBytes;
     if (copyBuffer == null)
       copyBuffer = new byte[COPY_BUFFER_SIZE];