Bug 59634: Clarify and refine JavaDoc of various close() methods to consistently state that close() invalidates the object

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

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

@@ -548,7 +548,7 @@ public final class HSSFWorkbook extends POIDocument implements org.apache.poi.ss
      * the 'active' sheet (which is the sheet with focus).
      * Unselects sheets that are not in <code>indexes</code>.
      *
-     * @param indexes
+     * @param indexes Array of sheets to select, the index is 0-based.
      */
     public void setSelectedTabs(int[] indexes) {
         Collection<Integer> list = new ArrayList<Integer>(indexes.length);
@@ -563,7 +563,7 @@ public final class HSSFWorkbook extends POIDocument implements org.apache.poi.ss
      * the 'active' sheet (which is the sheet with focus).
      * Unselects sheets that are not in <code>indexes</code>.
      *
-     * @param indexes
+     * @param indexes Collection of sheets to select, the index is 0-based.
      */
     public void setSelectedTabs(Collection<Integer> indexes) {
 
@@ -893,8 +893,7 @@ public final class HSSFWorkbook extends POIDocument implements org.apache.poi.ss
      */
     @Override
     public Iterator<Sheet> sheetIterator() {
-        Iterator<Sheet> result = new SheetIterator<Sheet>();
+        return new SheetIterator<Sheet>();
-        return result;
     }
 
     /**
@@ -1280,9 +1279,9 @@ public final class HSSFWorkbook extends POIDocument implements org.apache.poi.ss
 
     /**
      * Closes the underlying {@link NPOIFSFileSystem} from which
-     *  the Workbook was read, if any. Has no effect on Workbooks
+     *  the Workbook was read, if any.
-     *  opened from an InputStream, or newly created ones.
+     *
-     * <p>Once {@link #close()} has been called, no further 
+     * <p>Once this has been called, no further
      *  operations, updates or reads should be performed on the 
      *  Workbook.
      */

src/java/org/apache/poi/ss/usermodel/Workbook.java

@@ -341,9 +341,11 @@ public interface Workbook extends Closeable, Iterable<Sheet> {
 
     /**
      * Close the underlying input resource (File or Stream),
-     *  from which the Workbook was read. After closing, the
+     *  from which the Workbook was read.
-     *  Workbook should no longer be used.
+     *
-     * <p>This will have no effect newly created Workbooks.
+     * <p>Once this has been called, no further
+     *  operations, updates or reads should be performed on the
+     *  Workbook.
      */
     @Override
     void close() throws IOException;

src/ooxml/java/org/apache/poi/POIXMLDocument.java

@@ -193,8 +193,12 @@ public abstract class POIXMLDocument extends POIXMLDocumentPart implements Close
     /**
      * Closes the underlying {@link OPCPackage} from which this
      *  document was read, if there is one
-     * 
+     *
-     * @throws IOException for writable packages, if an IO exception occur during the saving process. 
+     * <p>Once this has been called, no further
+     *  operations, updates or reads should be performed on the
+     *  document.
+     *
+     * @throws IOException for writable packages, if an IO exception occur during the saving process.
      */
     @Override
     public void close() throws IOException {

src/ooxml/java/org/apache/poi/xssf/streaming/SXSSFWorkbook.java

@@ -893,8 +893,11 @@ public class SXSSFWorkbook implements Workbook {
 
     /**
      * Closes the underlying {@link XSSFWorkbook} and {@link OPCPackage} 
-     *  on which this Workbook is based, if any. Has no effect on Workbooks
+     *  on which this Workbook is based, if any.
-     *  created from scratch.
+     *
+     * <p>Once this has been called, no further
+     *  operations, updates or reads should be performed on the
+     *  Workbook.
      */
     @Override
     public void close() throws IOException {