JDK8 javadocs

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

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");

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<Row> {
      * @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);
     

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.
-     * <p/>
+     * <p>
      * Note that XSSF offers more kinds of document headers than HSSF does
      * </p>
      * @return the document header. Never <code>null</code>
@@ -784,9 +785,9 @@ public class SXSSFSheet implements Sheet
 
     /**
      * Gets the user model for the default document footer.
-     * <p/>
+     * <p>
      * Note that XSSF offers more kinds of document footers than HSSF does.
-     *
+     * </p>
      * @return the document footer. Never <code>null</code>
      */
     @Override
@@ -797,9 +798,9 @@ public class SXSSFSheet implements Sheet
 
     /**
      * Sets a flag indicating whether this sheet is selected.
-     *<p>
+     * <p>
      * Note: multiple sheets can be selected, but only one sheet can be active at one time.
-     *</p>
+     * </p>
      * @param value <code>true</code> 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:
      * <pre>
@@ -1308,7 +1310,7 @@ public class SXSSFSheet implements Sheet
      * </p>
      *
      * @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)
     {

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().
+     * Specifies how many rows can be accessed at most via {@link SXSSFSheet#getRow}.
-     * 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.
      */
     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.
+     * <p>Construct a workbook from a template.</p>
-     * <p>
+     * 
      * There are three use-cases to use SXSSFWorkbook(XSSFWorkbook) :
      * <ol>
      *   <li>
@@ -126,7 +126,7 @@ public class SXSSFWorkbook implements Workbook {
      *   </li>
      *   <li>
      *       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.
      *   </li>
      *   <li>
      *       Use existing workbook as a template and re-use global objects such
@@ -134,13 +134,13 @@ public class SXSSFWorkbook implements Workbook {
      *   </li>
      * </ol>
      * All three use cases can work in a combination.
-     * </p>
+     * 
      * What is not supported:
      * <ul>
      *   <li>
      *   Access initial cells and rows in the template. After constructing
-     *   SXSSFWorkbook(XSSFWorkbook) all internal windows are empty and
+     *   {@link #SXSSFWorkbook(XSSFWorkbook)} all internal windows are empty and
-     *   SXSSFSheet@getRow and SXSSFRow#getCell return null.
+     *   {@link SXSSFSheet#getRow} and {@link SXSSFRow#getCell} return <code>null</code>.
      *   </li>
      *   <li>
      *    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.
      * <p>
-     * 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.
      * </p>
      * <p>
-     * A value of -1 indicates unlimited access. In this case all
+     * A value of <code>-1</code> indicates unlimited access. In this case all
-     * records that have not been flushed by a call to flush() are available
+     * records that have not been flushed by a call to <code>flush()</code> are available
      * for random access.
+     * </p>
      * <p>
-     * <p></p>
+     * A value of <code>0</code> 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.
      * </p>
      *
@@ -182,18 +182,18 @@ public class SXSSFWorkbook implements Workbook {
     /**
      * Constructs an workbook from an existing workbook.
      * <p>
-     * 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.
      * </p>
      * <p>
-     * A value of -1 indicates unlimited access. In this case all
+     * A value of <code>-1</code> indicates unlimited access. In this case all
-     * records that have not been flushed by a call to flush() are available
+     * records that have not been flushed by a call to <code>flush()</code> are available
      * for random access.
+     * </p>
      * <p>
-     * <p></p>
+     * A value of <code>0</code> 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.
      * </p>
      *
@@ -207,18 +207,18 @@ public class SXSSFWorkbook implements Workbook {
     /**
      * Constructs an workbook from an existing workbook.
      * <p>
-     * 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.
      * </p>
      * <p>
-     * A value of -1 indicates unlimited access. In this case all
+     * A value of <code>-1</code> indicates unlimited access. In this case all
-     * records that have not been flushed by a call to flush() are available
+     * records that have not been flushed by a call to <code>flush()</code> are available
      * for random access.
+     * </p>
      * <p>
-     * <p></p>
+     * A value of <code>0</code> 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.
      * </p>
      *
@@ -250,18 +250,18 @@ public class SXSSFWorkbook implements Workbook {
     /**
      * Construct an empty workbook and specify the window for row access.
      * <p>
-     * 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.
      * </p>
      * <p>
-     * A value of -1 indicates unlimited access. In this case all
+     * A value of <code>-1</code> indicates unlimited access. In this case all
-     * records that have not been flushed by a call to flush() are available
+     * records that have not been flushed by a call to <code>flush()</code> are available
      * for random access.
+     * </p>
      * <p>
-     * <p></p>
+     * A value of <code>0</code> 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.
      * </p>
      *
@@ -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<br/>
+     * Gets the defined name index by name
+     * 
      * <i>Note:</i> 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. <tt>-1</tt> if not found.
+     * @return zero based index of the defined name. <code>-1</code> if not found.
      */
     @Override
     public int getNameIndex(String name)

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.</code>
+     * @return the cell's style.
      */
     @Override
     public XSSFCellStyle getCellStyle() {

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;