From 0c3aade7b12d15ca847cacccd10be4cab6e1da45 Mon Sep 17 00:00:00 2001 From: Javen O'Neal Date: Fri, 15 Jul 2016 06:35:21 +0000 Subject: [PATCH] JDK8 javadocs git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1752781 13f79535-47bb-0310-9956-ffa450edef68 --- .../apache/poi/hssf/usermodel/HSSFSheet.java | 3 +- .../org/apache/poi/ss/usermodel/Sheet.java | 2 + .../apache/poi/xssf/streaming/SXSSFSheet.java | 22 +++--- .../poi/xssf/streaming/SXSSFWorkbook.java | 73 ++++++++++--------- .../apache/poi/xssf/usermodel/XSSFCell.java | 2 +- .../apache/poi/xssf/usermodel/XSSFSheet.java | 2 + 6 files changed, 55 insertions(+), 49 deletions(-) diff --git a/src/java/org/apache/poi/hssf/usermodel/HSSFSheet.java b/src/java/org/apache/poi/hssf/usermodel/HSSFSheet.java index 698e20a06e..b1cf0fceda 100644 --- a/src/java/org/apache/poi/hssf/usermodel/HSSFSheet.java +++ b/src/java/org/apache/poi/hssf/usermodel/HSSFSheet.java @@ -1386,9 +1386,8 @@ public final class HSSFSheet implements org.apache.poi.ss.usermodel.Sheet { * * @param numerator The numerator for the zoom magnification. * @param denominator The denominator for the zoom magnification. - * @deprecated 2015-11-23 (circa POI 3.14beta1). Use {@link #setZoom(int)} instead. + * @see #setZoom(int) */ - @Override public void setZoom(int numerator, int denominator) { if (numerator < 1 || numerator > 65535) throw new IllegalArgumentException("Numerator must be greater than 0 and less than 65536"); diff --git a/src/java/org/apache/poi/ss/usermodel/Sheet.java b/src/java/org/apache/poi/ss/usermodel/Sheet.java index 34521fd437..3c064600b7 100644 --- a/src/java/org/apache/poi/ss/usermodel/Sheet.java +++ b/src/java/org/apache/poi/ss/usermodel/Sheet.java @@ -25,6 +25,7 @@ import java.util.Map; import org.apache.poi.ss.util.CellAddress; import org.apache.poi.ss.util.CellRangeAddress; import org.apache.poi.ss.util.PaneInformation; +import org.apache.poi.util.Removal; /** * High level representation of a Excel worksheet. @@ -624,6 +625,7 @@ public interface Sheet extends Iterable { * @param denominator The denominator for the zoom magnification. * @deprecated 2015-11-23 (circa POI 3.14beta1). Use {@link #setZoom(int)} instead. */ + @Removal(version="3.16") @Deprecated void setZoom(int numerator, int denominator); diff --git a/src/ooxml/java/org/apache/poi/xssf/streaming/SXSSFSheet.java b/src/ooxml/java/org/apache/poi/xssf/streaming/SXSSFSheet.java index d87d4d9b62..db75ca6d55 100644 --- a/src/ooxml/java/org/apache/poi/xssf/streaming/SXSSFSheet.java +++ b/src/ooxml/java/org/apache/poi/xssf/streaming/SXSSFSheet.java @@ -47,6 +47,7 @@ import org.apache.poi.ss.util.PaneInformation; import org.apache.poi.ss.util.SheetUtil; import org.apache.poi.util.Internal; import org.apache.poi.util.NotImplemented; +import org.apache.poi.util.Removal; import org.apache.poi.xssf.usermodel.XSSFColor; import org.apache.poi.xssf.usermodel.XSSFComment; import org.apache.poi.xssf.usermodel.XSSFDataValidation; @@ -771,7 +772,7 @@ public class SXSSFSheet implements Sheet /** * Gets the user model for the default document header. - *

+ *

* Note that XSSF offers more kinds of document headers than HSSF does *

* @return the document header. Never null @@ -784,9 +785,9 @@ public class SXSSFSheet implements Sheet /** * Gets the user model for the default document footer. - *

+ *

* Note that XSSF offers more kinds of document footers than HSSF does. - * + *

* @return the document footer. Never null */ @Override @@ -797,9 +798,9 @@ public class SXSSFSheet implements Sheet /** * Sets a flag indicating whether this sheet is selected. - *

+ *

* Note: multiple sheets can be selected, but only one sheet can be active at one time. - *

+ *

* @param value true if this sheet is selected * @see Workbook#setActiveSheet(int) */ @@ -836,7 +837,7 @@ public class SXSSFSheet implements Sheet /** * Answer whether protection is enabled or disabled * - * @return true => protection enabled; false => protection disabled + * @return true means protection enabled; false means protection disabled */ @Override public boolean getProtect() @@ -857,7 +858,7 @@ public class SXSSFSheet implements Sheet /** * Answer whether scenario protection is enabled or disabled * - * @return true => protection enabled; false => protection disabled + * @return true means protection enabled; false means protection disabled */ @Override public boolean getScenarioProtect() @@ -866,7 +867,7 @@ public class SXSSFSheet implements Sheet } /** - * Sets the zoom magnication for the sheet. The zoom is expressed as a + * Sets the zoom magnification for the sheet. The zoom is expressed as a * fraction. For example to express a zoom of 75% use 3 for the numerator * and 4 for the denominator. * @@ -874,6 +875,7 @@ public class SXSSFSheet implements Sheet * @param denominator The denominator for the zoom magnification. * @deprecated 2015-11-23 (circa POI 3.14beta1). Use {@link #setZoom(int)} instead. */ + @Removal(version="3.16") @Override public void setZoom(int numerator, int denominator) { @@ -882,7 +884,7 @@ public class SXSSFSheet implements Sheet /** * Window zoom magnification for current view representing percent values. - * Valid values range from 10 to 400. Horizontal & Vertical scale together. + * Valid values range from 10 to 400. Horizontal and Vertical scale together. * * For example: * 
@@ -1308,7 +1310,7 @@ public class SXSSFSheet implements Sheet
      * 

      *
      * @param rownum    index of row to update (0-based)
-     * @param level     outline level (> 0)
+     * @param level     outline level (greater than 0)
      */
     public void setRowOutlineLevel(int rownum, int level)
     {
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 8188c9e725..6993579cc0 100644
--- a/src/ooxml/java/org/apache/poi/xssf/streaming/SXSSFWorkbook.java
+++ b/src/ooxml/java/org/apache/poi/xssf/streaming/SXSSFWorkbook.java
@@ -82,11 +82,11 @@ import org.apache.poi.xssf.usermodel.XSSFWorkbook;
  */
 public class SXSSFWorkbook implements Workbook {
     /**
-     * Specifies how many rows can be accessed at most via getRow().
-     * When a new node is created via createRow() and the total number
+     * Specifies how many rows can be accessed at most via {@link SXSSFSheet#getRow}.
+     * When a new node is created via {@link SXSSFSheet#createRow} and the total number
      * of unflushed records would exceed the specified value, then the
      * row with the lowest index value is flushed and cannot be accessed
-     * via getRow() anymore.
+     * via {@link SXSSFSheet#getRow} anymore.
      */
     public static final int DEFAULT_WINDOW_SIZE = 100;
     private static final POILogger logger = POILogFactory.getLogger(SXSSFWorkbook.class);
@@ -116,8 +116,8 @@ public class SXSSFWorkbook implements Workbook {
     }
 
     /**
-     * Construct a workbook from a template.
-     * 

+     * 
Construct a workbook from a template.

+     * 
      * There are three use-cases to use SXSSFWorkbook(XSSFWorkbook) :
      * 
    
      *   
  1. 
@@ -126,7 +126,7 @@ public class SXSSFWorkbook implements Workbook {
      *   
    2. 
      *   
  2. 
      *       Append rows to existing sheets. The row number MUST be greater
-     *       than max(rownum) in the template sheet.
+     *       than {@code max(rownum)} in the template sheet.
      *   
    3. 
      *   
  3. 
      *       Use existing workbook as a template and re-use global objects such
@@ -134,13 +134,13 @@ public class SXSSFWorkbook implements Workbook {
      *   
    4. 
      * 

      * All three use cases can work in a combination.
-     * 

+     * 
      * What is not supported:
      * 
    
      *   
  • 
      *   Access initial cells and rows in the template. After constructing
-     *   SXSSFWorkbook(XSSFWorkbook) all internal windows are empty and
-     *   SXSSFSheet@getRow and SXSSFRow#getCell return null.
+     *   {@link #SXSSFWorkbook(XSSFWorkbook)} all internal windows are empty and
+     *   {@link SXSSFSheet#getRow} and {@link SXSSFRow#getCell} return null.
      *   
    • 
      *   
  • 
      *    Override existing cells and rows. The API silently allows that but
@@ -158,18 +158,18 @@ public class SXSSFWorkbook implements Workbook {
     /**
      * Constructs an workbook from an existing workbook.
      * 
    
-     * When a new node is created via createRow() and the total number
+     * When a new node is created via {@link SXSSFSheet#createRow} and the total number
      * of unflushed records would exceed the specified value, then the
      * row with the lowest index value is flushed and cannot be accessed
-     * via getRow() anymore.
+     * via {@link SXSSFSheet#getRow} anymore.
      * 
    
      * 
    
-     * A value of -1 indicates unlimited access. In this case all
-     * records that have not been flushed by a call to flush() are available
+     * A value of -1 indicates unlimited access. In this case all
+     * records that have not been flushed by a call to flush() are available
      * for random access.
+     * 
    
      * 
    
-     * 
    
-     * A value of 0 is not allowed because it would flush any newly created row
+     * A value of 0 is not allowed because it would flush any newly created row
      * without having a chance to specify any cells.
      * 
    
      *
@@ -182,18 +182,18 @@ public class SXSSFWorkbook implements Workbook {
     /**
      * Constructs an workbook from an existing workbook.
      * 
    
-     * When a new node is created via createRow() and the total number
+     * When a new node is created via {@link SXSSFSheet#createRow} and the total number
      * of unflushed records would exceed the specified value, then the
      * row with the lowest index value is flushed and cannot be accessed
-     * via getRow() anymore.
+     * via {@link SXSSFSheet#getRow} anymore.
      * 
    
      * 
    
-     * A value of -1 indicates unlimited access. In this case all
-     * records that have not been flushed by a call to flush() are available
+     * A value of -1 indicates unlimited access. In this case all
+     * records that have not been flushed by a call to flush() are available
      * for random access.
+     * 
    
      * 
    
-     * 
    
-     * A value of 0 is not allowed because it would flush any newly created row
+     * A value of 0 is not allowed because it would flush any newly created row
      * without having a chance to specify any cells.
      * 
    
      *
@@ -207,18 +207,18 @@ public class SXSSFWorkbook implements Workbook {
     /**
      * Constructs an workbook from an existing workbook.
      * 
    
-     * When a new node is created via createRow() and the total number
+     * When a new node is created via {@link SXSSFSheet#createRow} and the total number
      * of unflushed records would exceed the specified value, then the
      * row with the lowest index value is flushed and cannot be accessed
-     * via getRow() anymore.
+     * via {@link SXSSFSheet#getRow} anymore.
      * 
    
      * 
    
-     * A value of -1 indicates unlimited access. In this case all
-     * records that have not been flushed by a call to flush() are available
+     * A value of -1 indicates unlimited access. In this case all
+     * records that have not been flushed by a call to flush() are available
      * for random access.
+     * 
    
      * 
    
-     * 
    
-     * A value of 0 is not allowed because it would flush any newly created row
+     * A value of 0 is not allowed because it would flush any newly created row
      * without having a chance to specify any cells.
      * 
    
      *
@@ -250,18 +250,18 @@ public class SXSSFWorkbook implements Workbook {
     /**
      * Construct an empty workbook and specify the window for row access.
      * 
    
-     * When a new node is created via createRow() and the total number
+     * When a new node is created via {@link SXSSFSheet#createRow} and the total number
      * of unflushed records would exceed the specified value, then the
      * row with the lowest index value is flushed and cannot be accessed
-     * via getRow() anymore.
+     * via {@link SXSSFSheet#getRow} anymore.
      * 
    
      * 
    
-     * A value of -1 indicates unlimited access. In this case all
-     * records that have not been flushed by a call to flush() are available
+     * A value of -1 indicates unlimited access. In this case all
+     * records that have not been flushed by a call to flush() are available
      * for random access.
+     * 
    
      * 
    
-     * 
    
-     * A value of 0 is not allowed because it would flush any newly created row
+     * A value of 0 is not allowed because it would flush any newly created row
      * without having a chance to specify any cells.
      * 
    
      *
@@ -754,7 +754,7 @@ public class SXSSFWorkbook implements Workbook {
     /**
      * Get the Sheet object at the given index.
      *
-     * @param index of the sheet number (0-based physical & logical)
+     * @param index of the sheet number (0-based physical and logical)
      * @return Sheet at the provided index
      */
     @Override
@@ -1026,12 +1026,13 @@ public class SXSSFWorkbook implements Workbook {
     }
 
     /**
-     * Gets the defined name index by name
    
+     * Gets the defined name index by name
+     * 
      * Note: Excel defined names are case-insensitive and
      * this method performs a case-insensitive search.
      *
      * @param name the name of the defined name
-     * @return zero based index of the defined name. -1 if not found.
+     * @return zero based index of the defined name. -1 if not found.
      */
     @Override
     public int getNameIndex(String name)
diff --git a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java
index b0287e05c8..4aa2f037e7 100644
--- a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java
+++ b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java
@@ -618,7 +618,7 @@ public final class XSSFCell implements Cell {
     /**
      * Return the cell's style.
      *
-     * @return the cell's style.
+     * @return the cell's style.
      */
     @Override
     public XSSFCellStyle getCellStyle() {
diff --git a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFSheet.java b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFSheet.java
index efd45943fa..c7cb28f5b9 100644
--- a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFSheet.java
+++ b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFSheet.java
@@ -78,6 +78,7 @@ import org.apache.poi.util.Beta;
 import org.apache.poi.util.Internal;
 import org.apache.poi.util.POILogFactory;
 import org.apache.poi.util.POILogger;
+import org.apache.poi.util.Removal;
 import org.apache.poi.xssf.model.CommentsTable;
 import org.apache.poi.xssf.usermodel.helpers.ColumnHelper;
 import org.apache.poi.xssf.usermodel.helpers.XSSFIgnoredErrorHelper;
@@ -2740,6 +2741,7 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet {
      * @param denominator   The denominator for the zoom magnification.
      * @deprecated 2015-11-23 (circa POI 3.14beta1). Use {@link #setZoom(int)} instead.
      */
+    @Removal(version="3.16")
     @Override
     public void setZoom(int numerator, int denominator) {
         int zoom = 100*numerator/denominator;
-- 
2.39.5