[GitHub] [lucene] mikemccand commented on a diff in pull request #884: LUCENE-10568: fix javadocs errors in IndexWriter.DocStats

[GitBox <gi...@apache.org>]

mikemccand commented on code in PR #884:
URL: https://github.com/apache/lucene/pull/884#discussion_r871492434


##########
lucene/core/src/java/org/apache/lucene/index/IndexWriter.java:
##########
@@ -6199,13 +6199,14 @@ public synchronized DocStats getDocStats() {
   public static final class DocStats {
     /**
      * The total number of docs in this index, including docs not yet flushed (still in the RAM
-     * buffer), not counting deletions.
+     * buffer), and including deletions. <b>NOTE:</b> buffered deletions are not counted. If you

Review Comment:
   I find both `including deletions` and `not counting deletions` to be horribly ambiguous!  I could read each of them in either direction.
   
   Could we avoid `including` and `not counting` and instead say something like `and also counting deleted documents`?



##########
lucene/core/src/java/org/apache/lucene/index/IndexWriter.java:
##########
@@ -6199,13 +6199,14 @@ public synchronized DocStats getDocStats() {
   public static final class DocStats {
     /**
      * The total number of docs in this index, including docs not yet flushed (still in the RAM
-     * buffer), not counting deletions.
+     * buffer), and including deletions. <b>NOTE:</b> buffered deletions are not counted. If you
+     * really need these to be counted you should call {@link IndexWriter#commit()} first.
      */
     public final int maxDoc;
+
     /**
      * The total number of docs in this index, including docs not yet flushed (still in the RAM
-     * buffer), and including deletions. <b>NOTE:</b> buffered deletions are not counted. If you
-     * really need these to be counted you should call {@link IndexWriter#commit()} first.
+     * buffer), not counting deletions.

Review Comment:
   ... and how about `not counting deleted documents`?
   
   And maybe we could insert a simple equation in both javadocs: `numDocs = maxDocs - deletedDocCount` or so?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org