From a3c48b5ac411df4813bf17840186cddcddb04a25 Mon Sep 17 00:00:00 2001
From: Michael McCandless <mikemccand@apache.org>
Date: Fri, 17 Jan 2014 13:37:14 +0000
Subject: [PATCH] improve javadocs

git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/trunk@1559103 13f79535-47bb-0310-9956-ffa450edef68
---
 .../org/apache/lucene/index/IndexWriter.java  | 21 ++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)

diff --git a/lucene/core/src/java/org/apache/lucene/index/IndexWriter.java b/lucene/core/src/java/org/apache/lucene/index/IndexWriter.java
index b3d7d521e14..93b7732fbbe 100644
--- a/lucene/core/src/java/org/apache/lucene/index/IndexWriter.java
+++ b/lucene/core/src/java/org/apache/lucene/index/IndexWriter.java
@@ -1112,7 +1112,11 @@ public class IndexWriter implements Closeable, TwoPhaseCommit{
   }
 
   /**
-   * Returns true if this index has deletions (including buffered deletions).
+   * Returns true if this index has deletions (including
+   * buffered deletions).  Note that this will return true
+   * if there are buffered Term/Query deletions, even if it
+   * turns out those buffered deletions don't match any
+   * documents.
    */
   public synchronized boolean hasDeletions() {
     ensureOpen();
@@ -2893,12 +2897,15 @@ public class IndexWriter implements Closeable, TwoPhaseCommit{
     commitInternal();
   }
 
-  /** Returns true if there are changes that have not been
-   *  committed.  Note that if a merge kicked off as a
-   *  result of flushing a new segment during {@link
-   *  #commit}, or a concurrent merged finished,
-   *  this method may return true right after you
-   *  had just called {@link #commit}. */
+  /** Returns true if there may be changes that have not been
+   *  committed.  There are cases where this may return true
+   *  when there are no actual "real" changes to the index,
+   *  for example if you've deleted by Term or Query but
+   *  that Term or Query does not match any documents.
+   *  Also, if a merge kicked off as a result of flushing a
+   *  new segment during {@link #commit}, or a concurrent
+   *  merged finished, this method may return true right
+   *  after you had just called {@link #commit}. */
   public final boolean hasUncommittedChanges() {
     return changeCount != lastCommitChangeCount || docWriter.anyChanges() || bufferedUpdatesStream.any();
   }