diff --git a/src/java/org/apache/lucene/index/IndexWriter.java b/src/java/org/apache/lucene/index/IndexWriter.java
index 76487e11b82..42fefa08121 100644
--- a/src/java/org/apache/lucene/index/IndexWriter.java
+++ b/src/java/org/apache/lucene/index/IndexWriter.java
@@ -774,25 +774,33 @@ public class IndexWriter {
     return mergeScheduler;
   }
 
-  /** Determines the largest number of documents ever merged by addDocument().
-   * Small values (e.g., less than 10,000) are best for interactive indexing,
-   * as this limits the length of pauses while indexing to a few seconds.
-   * Larger values are best for batched indexing and speedier searches.
+  /** <p>Determines the largest segment (measured by
+   * document count) that may be merged with other segments.
+   * Small values (e.g., less than 10,000) are best for
+   * interactive indexing, as this limits the length of
+   * pauses while indexing to a few seconds.  Larger values
+   * are best for batched indexing and speedier
+   * searches.</p>
    *
-   * <p>The default value is {@link Integer#MAX_VALUE}.
+   * <p>The default value is {@link Integer#MAX_VALUE}.</p>
    *
    * <p>Note that this method is a convenience method: it
    * just calls mergePolicy.setMaxMergeDocs as long as
    * mergePolicy is an instance of {@link LogMergePolicy}.
    * Otherwise an IllegalArgumentException is thrown.</p>
+   *
+   * <p>The default merge policy ({@link
+   * LogByteSizeMergePolicy}) also allows you to set this
+   * limit by net size (in MB) of the segment, using {@link
+   * LogByteSizeMergePolicy#setMaxMergeMB}.</p>
    */
   public void setMaxMergeDocs(int maxMergeDocs) {
     getLogMergePolicy().setMaxMergeDocs(maxMergeDocs);
   }
 
-   /**
-   * Returns the largest number of documents allowed in a
-   * single segment.
+  /**
+   * <p>Returns the largest segment (measured by document
+   * count) that may be merged with other segments.</p>
    *
    * <p>Note that this method is a convenience method: it
    * just calls mergePolicy.getMaxMergeDocs as long as
diff --git a/src/java/org/apache/lucene/index/LogByteSizeMergePolicy.java b/src/java/org/apache/lucene/index/LogByteSizeMergePolicy.java
index 72fcfe81c0a..c2ba59d2f16 100644
--- a/src/java/org/apache/lucene/index/LogByteSizeMergePolicy.java
+++ b/src/java/org/apache/lucene/index/LogByteSizeMergePolicy.java
@@ -39,16 +39,24 @@ public class LogByteSizeMergePolicy extends LogMergePolicy {
     return info.sizeInBytes();
   }
 
-  /** Sets the maximum size for a segment to be merged.
-   *  When a segment is this size or larger it will never be
-   *  merged.  Note that {@link #setMaxMergeDocs} is also
+  /** <p>Determines the largest segment (measured by total
+   *  byte size of the segment's files, in MB) that may be
+   *  merged with other segments.  Small values (e.g., less
+   *  than 50 MB) are best for interactive indexing, as this
+   *  limits the length of pauses while indexing to a few
+   *  seconds.  Larger values are best for batched indexing
+   *  and speedier searches.</p>
+   *
+   *  <p>Note that {@link #setMaxMergeDocs} is also
    *  used to check whether a segment is too large for
-   *  merging (it's either or). */
+   *  merging (it's either or).</p>*/
   public void setMaxMergeMB(double mb) {
     maxMergeSize = (long) (mb*1024*1024);
   }
 
-  /** Get the maximum size for a segment to be merged.
+  /** Returns the largest segment (meaured by total byte
+   *  size of the segment's files, in MB) that may be merged
+   *  with other segments.
    *  @see #setMaxMergeMB */
   public double getMaxMergeMB() {
     return ((double) maxMergeSize)/1024/1024;
diff --git a/src/java/org/apache/lucene/index/LogMergePolicy.java b/src/java/org/apache/lucene/index/LogMergePolicy.java
index 0657f5a8c3d..66f7bf5358a 100644
--- a/src/java/org/apache/lucene/index/LogMergePolicy.java
+++ b/src/java/org/apache/lucene/index/LogMergePolicy.java
@@ -309,14 +309,27 @@ public abstract class LogMergePolicy implements MergePolicy {
     return spec;
   }
 
-  /** Sets the maximum docs for a segment to be merged.
-   *  When a segment has this many docs or more it will never be
-   *  merged. */
+  /** <p>Determines the largest segment (measured by
+   * document count) that may be merged with other segments.
+   * Small values (e.g., less than 10,000) are best for
+   * interactive indexing, as this limits the length of
+   * pauses while indexing to a few seconds.  Larger values
+   * are best for batched indexing and speedier
+   * searches.</p>
+   *
+   * <p>The default value is {@link Integer#MAX_VALUE}.</p>
+   *
+   * <p>The default merge policy ({@link
+   * LogByteSizeMergePolicy}) also allows you to set this
+   * limit by net size (in MB) of the segment, using {@link
+   * LogByteSizeMergePolicy#setMaxMergeMB}.</p>
+   */
   public void setMaxMergeDocs(int maxMergeDocs) {
     this.maxMergeDocs = maxMergeDocs;
   }
 
-  /** Get the maximum docs for a segment to be merged.
+  /** Returns the largest segment (measured by document
+   *  count) that may be merged with other segments.
    *  @see #setMaxMergeDocs */
   public int getMaxMergeDocs() {
     return maxMergeDocs;