Improve JavaDocs about iterators and gaps

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

src/java/org/apache/poi/hssf/usermodel/HSSFRow.java

@@ -479,8 +479,10 @@ public final class HSSFRow implements Comparable {
     }
 
     /**
-     * @return cell iterator of the physically defined cells.  Note element 4 may
-     * actually be row cell depending on how many are defined!
+     * @return cell iterator of the physically defined cells. 
+     * Note that the 4th element might well not be cell 4, as the iterator
+     *  will not return un-defined (null) cells.
+     * Call getCellNum() on the returned cells to know which cell they are.
      */
     public Iterator cellIterator()
     {

src/java/org/apache/poi/hssf/usermodel/HSSFSheet.java

@@ -699,6 +699,7 @@ public final class HSSFSheet {
     /**
      * @return an iterator of the PHYSICAL rows.  Meaning the 3rd element may not
      * be the third row if say for instance the second row is undefined.
+     * Call getRowNum() on each row if you care which one it is.
      */
     public Iterator rowIterator()
     {