Bug 61082: Adjust JavaDoc for getFirst/LastRow/Cell to explain that there might be empty rows/cells included in the counts

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

2 files changed, 21 insertions, 1 deletions

diff --git a/src/java/org/apache/poi/ss/usermodel/Row.java b/src/java/org/apache/poi/ss/usermodel/Row.java
index 4f5645a0e0..20507fe0e3 100644
--- a/src/java/org/apache/poi/ss/usermodel/Row.java
+++ b/src/java/org/apache/poi/ss/usermodel/Row.java
@@ -118,6 +118,11 @@ public interface Row extends Iterable<Cell> {
     /**
      * Get the number of the first cell contained in this row.
      *
+     * Note: cells which had content before and were set to empty later might
+     * still be counted as cells by Excel and Apache POI, so the result of this
+     * method will include such rows and thus the returned value might be lower
+     * than expected!
+     *
      * @return short representing the first logical cell in the row,
      *  or -1 if the row does not contain any cells.
      */
@@ -139,6 +144,11 @@ public interface Row extends Iterable<Cell> {
      * }
      * </pre>
      *
+     * Note: cells which had content before and were set to empty later might
+     * still be counted as cells by Excel and Apache POI, so the result of this
+     * method will include such rows and thus the returned value might be higher
+     * than expected!
+     *
      * @return short representing the last logical cell in the row <b>PLUS ONE</b>,
      *   or -1 if the row does not contain any cells.
      */
diff --git a/src/java/org/apache/poi/ss/usermodel/Sheet.java b/src/java/org/apache/poi/ss/usermodel/Sheet.java
index 80788a09a1..a0d1a3de7b 100644
--- a/src/java/org/apache/poi/ss/usermodel/Sheet.java
+++ b/src/java/org/apache/poi/ss/usermodel/Sheet.java
@@ -91,7 +91,12 @@ public interface Sheet extends Iterable<Row> {
     int getPhysicalNumberOfRows();
 
     /**
-     * Gets the first row on the sheet
+     * Gets the first row on the sheet.
+     *
+     * Note: rows which had content before and were set to empty later might
+     * still be counted as rows by Excel and Apache POI, so the result of this
+     * method will include such rows and thus the returned value might be lower
+     * than expected!
      *
      * @return the number of the first logical row on the sheet (0-based)
      */
@@ -100,6 +105,11 @@ public interface Sheet extends Iterable<Row> {
     /**
      * Gets the last row on the sheet
      *
+     * Note: rows which had content before and were set to empty later might
+     * still be counted as rows by Excel and Apache POI, so the result of this
+     * method will include such rows and thus the returned value might be higher
+     * than expected!
+     *
      * @return last row contained n this sheet (0-based)
      */
     int getLastRowNum();