Bug 59634: Clarify and refine JavaDoc of various close() methods to consistently...

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

diff --git a/src/java/org/apache/poi/hssf/usermodel/HSSFWorkbook.java b/src/java/org/apache/poi/hssf/usermodel/HSSFWorkbook.java
index 123d8d3329767f8e7ed69e7fe20a709f1a886d49..35f9862116c39a469673adc3005250f10161a6bc 100644 (file)
--- a/src/java/org/apache/poi/hssf/usermodel/HSSFWorkbook.java
+++ b/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 result;
+        return new SheetIterator<Sheet>();
     }
 
     /**
@@ -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
-     *  opened from an InputStream, or newly created ones.
-     * <p>Once {@link #close()} has been called, no further 
+     *  the Workbook was read, if any.
+     *
+     * <p>Once this has been called, no further
      *  operations, updates or reads should be performed on the 
      *  Workbook.
      */

diff --git a/src/java/org/apache/poi/ss/usermodel/Workbook.java b/src/java/org/apache/poi/ss/usermodel/Workbook.java
index 1fcc29a3eb849e36339327be3e070d87fdbd3149..f1f1a4cd2c2d3c92faa181b4768d413d7e0b43d6 100644 (file)
--- a/src/java/org/apache/poi/ss/usermodel/Workbook.java
+++ b/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
-     *  Workbook should no longer be used.
-     * <p>This will have no effect newly created Workbooks.
+     *  from which the Workbook was read.
+     *
+     * <p>Once this has been called, no further
+     *  operations, updates or reads should be performed on the
+     *  Workbook.
      */
     @Override
     void close() throws IOException;

diff --git a/src/ooxml/java/org/apache/poi/POIXMLDocument.java b/src/ooxml/java/org/apache/poi/POIXMLDocument.java
index 55b1a4d1866b004d54d6e2300a84ee49e1296cc2..4ec3d442ed218ab5a04be4fc229af5a39d831fde 100644 (file)
--- a/src/ooxml/java/org/apache/poi/POIXMLDocument.java
+++ b/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 {

diff --git a/src/ooxml/java/org/apache/poi/xssf/streaming/SXSSFWorkbook.java b/src/ooxml/java/org/apache/poi/xssf/streaming/SXSSFWorkbook.java
index 6993579cc081aed98f7ffd2624fbe9b4ef928d6b..58e16c772ce3f6dfb311352d712550336526bed4 100644 (file)
--- a/src/ooxml/java/org/apache/poi/xssf/streaming/SXSSFWorkbook.java
+++ b/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
-     *  created from scratch.
+     *  on which this Workbook is based, if any.
+     *
+     * <p>Once this has been called, no further
+     *  operations, updates or reads should be performed on the
+     *  Workbook.
      */
     @Override
     public void close() throws IOException {