bug 59804: indicate when features were @Internal-ized

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

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

@@ -151,7 +151,7 @@ public class HSSFCell implements Cell {
                        CellType type)
     {
         checkBounds(col);
-        _cellType     = CellType._UNINITIALIZED; // Force 'setCellType' to create a first Record
+        _cellType     = CellType._NONE; // Force 'setCellType' to create a first Record
         _stringValue  = null;
         _book    = book;
         _sheet   = sheet;
@@ -434,7 +434,7 @@ public class HSSFCell implements Cell {
                 throw new IllegalStateException("Invalid cell type: " + cellType);
         }
         if (cellType != _cellType &&
-            _cellType != CellType._UNINITIALIZED )  // Special Value to indicate an uninitialized Cell
+            _cellType != CellType._NONE )  // Special Value to indicate an uninitialized Cell
         {
             _sheet.getSheet().replaceValueRecord(_record);
         }
@@ -459,7 +459,7 @@ public class HSSFCell implements Cell {
      * @deprecated POI 3.15 beta 3
      * Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     @Override
     public CellType getCellTypeEnum()
     {
@@ -1169,7 +1169,7 @@ public class HSSFCell implements Cell {
      * @deprecated POI 3.15 beta 3
      * Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     @Override
     public CellType getCachedFormulaResultTypeEnum() {
         if (_cellType != CellType.FORMULA) {

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

@@ -65,7 +65,7 @@ final class HSSFEvaluationCell implements EvaluationCell {
 	 * @deprecated POI 3.15 beta 3.
 	 * Will be deleted when we make the CellType enum transition. See bug 59791.
 	 */
-	@Internal
+	@Internal(since="POI 3.15 beta 3")
 	@Override
 	public CellType getCellTypeEnum() {
 		return _cell.getCellTypeEnum();
@@ -109,7 +109,7 @@ final class HSSFEvaluationCell implements EvaluationCell {
 	 * @deprecated POI 3.15 beta 3.
 	 * Will be deleted when we make the CellType enum transition. See bug 59791.
 	 */
-	@Internal
+	@Internal(since="POI 3.15 beta 3")
 	@Override
 	public CellType getCachedFormulaResultTypeEnum() {
 		return _cell.getCachedFormulaResultTypeEnum();

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

@@ -220,25 +220,26 @@ public class HSSFFormulaEvaluator implements FormulaEvaluator, WorkbookEvaluator
 	
 	/**
 	 * If cell contains formula, it evaluates the formula, and saves the result of the formula. The
-	 * cell remains as a formula cell. If the cell does not contain formula, this method returns -1
-	 * and leaves the cell unchanged.
+	 * cell remains as a formula cell. If the cell does not contain formula, rather than throwing an
+	 * exception, this method returns {@link CellType#_NONE} and leaves the cell unchanged.
 	 *
 	 * Note that the type of the <em>formula result</em> is returned, so you know what kind of
 	 * cached formula result is also stored with  the formula.
 	 * <pre>
-	 * int evaluatedCellType = evaluator.evaluateFormulaCell(cell);
+	 * CellType evaluatedCellType = evaluator.evaluateFormulaCell(cell);
 	 * </pre>
 	 * Be aware that your cell will hold both the formula, and the result. If you want the cell
 	 * replaced with the result of the formula, use {@link #evaluateInCell(org.apache.poi.ss.usermodel.Cell)}
 	 * @param cell The cell to evaluate
-	 * @return -1 for non-formula cells, or the type of the <em>formula result</em>
+	 * @return {@link CellType#_NONE} for non-formula cells, or the type of the <em>formula result</em>
+	 * @since POI 3.15 beta 3
 	 * @deprecated POI 3.15 beta 3. Will be deleted when we make the CellType enum transition. See bug 59791.
 	 */
 	@Internal
 	@Override
 	public CellType evaluateFormulaCellEnum(Cell cell) {
 		if (cell == null || cell.getCellTypeEnum() != CellType.FORMULA) {
-			return CellType._UNINITIALIZED;
+			return CellType._NONE;
 		}
 		CellValue cv = evaluateFormulaCellValue(cell);
 		// cell remains a formula cell, but the cached value is changed

src/java/org/apache/poi/ss/format/CellFormat.java

@@ -439,7 +439,7 @@ public class CellFormat {
      * @deprecated POI 3.15 beta 3
      * Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     public static CellType ultimateTypeEnum(Cell cell) {
         CellType type = cell.getCellTypeEnum();
         if (type == CellType.FORMULA)

src/java/org/apache/poi/ss/formula/eval/forked/ForkedEvaluationCell.java

@@ -118,7 +118,7 @@ final class ForkedEvaluationCell implements EvaluationCell {
 	 * @deprecated POI 3.15 beta 3.
 	 * Will be deleted when we make the CellType enum transition. See bug 59791.
 	 */
-	@Internal
+	@Internal(since="POI 3.15 beta 3")
 	@Override
 	public CellType getCellTypeEnum() {
 		return _cellType;
@@ -170,7 +170,7 @@ final class ForkedEvaluationCell implements EvaluationCell {
 	 * @deprecated POI 3.15 beta 3.
 	 * Will be deleted when we make the CellType enum transition. See bug 59791.
 	 */
-	@Internal
+	@Internal(since="POI 3.15 beta 3")
 	@Override
 	public CellType getCachedFormulaResultTypeEnum() {
 		return _masterCell.getCachedFormulaResultTypeEnum();

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

@@ -170,7 +170,7 @@ public interface Cell {
      * @deprecated POI 3.15 beta 3
      * Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     CellType getCellTypeEnum();
     
     /**
@@ -194,7 +194,7 @@ public interface Cell {
      * @deprecated POI 3.15 beta 3
      * Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     CellType getCachedFormulaResultTypeEnum();
 
     /**

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

@@ -24,13 +24,20 @@ import org.apache.poi.util.Internal;
  * @since POI 3.15 beta 3
  */
 public enum CellType {
-    @Internal
-    _UNINITIALIZED(-1),
+    /**
+     * Unknown type, used to represent a state prior to initialization or the
+     * lack of a concrete type.
+     * For internal use only.
+     */
+    @Internal(since="POI 3.15 beta 3")
+    _NONE(-1),
 
-    /** Numeric cell type (whole numbers, fractional numbers, dates) */
+    /**
+     * Numeric cell type (whole numbers, fractional numbers, dates)
+     */
     NUMERIC(0),
     
-    /** String cell type */
+    /** String (text) cell type */
     STRING(1),
     
     /**

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

@@ -126,7 +126,7 @@ public interface FormulaEvaluator {
      *      Note: the cell's type remains as CellType.FORMULA however.
      * @deprecated POI 3.15 beta 3. Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     CellType evaluateFormulaCellEnum(Cell cell);
 
     /**

src/java/org/apache/poi/ss/util/SheetUtil.java

@@ -93,8 +93,11 @@ public class SheetUtil {
         public int evaluateFormulaCell(Cell cell) {
             return cell.getCachedFormulaResultType();
         }
-        /** @deprecated POI 3.15 beta 3. Will be deleted when we make the CellType enum transition. See bug 59791. */
-        @Internal
+        /** 
+         * @since POI 3.15 beta 3
+         * @deprecated POI 3.15 beta 3. Will be deleted when we make the CellType enum transition. See bug 59791.
+         */
+        @Internal(since="POI 3.15 beta 3")
         @Override
         public CellType evaluateFormulaCellEnum(Cell cell) {
             return cell.getCachedFormulaResultTypeEnum();

src/java/org/apache/poi/util/BitField.java

@@ -25,7 +25,7 @@ package org.apache.poi.util;
  * @author Marc Johnson (mjohnson at apache dot org)
  * @author Andrew C. Oliver (acoliver at apache dot org)
  */
-@Internal
+@Internal(since="POI 3.15 beta 3")
 public class BitField
 {
     private final int _mask;

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

@@ -174,7 +174,7 @@ public class SXSSFCell implements Cell {
      * @deprecated POI 3.15 beta 3
      * Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     @Override
     public CellType getCellTypeEnum()
     {
@@ -202,7 +202,7 @@ public class SXSSFCell implements Cell {
      * @deprecated POI 3.15 beta 3.
      * Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     @Override
     public CellType getCachedFormulaResultTypeEnum()
     {

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

@@ -67,7 +67,7 @@ final class SXSSFEvaluationCell implements EvaluationCell {
      * @deprecated POI 3.15 beta 3.
      * Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     @Override
     public CellType getCellTypeEnum() {
         return _cell.getCellTypeEnum();
@@ -111,7 +111,7 @@ final class SXSSFEvaluationCell implements EvaluationCell {
      * @deprecated POI 3.15 beta 3.
      * Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     @Override
     public CellType getCachedFormulaResultTypeEnum() {
         return _cell.getCachedFormulaResultTypeEnum();

src/ooxml/java/org/apache/poi/xssf/usermodel/BaseXSSFFormulaEvaluator.java

@@ -134,12 +134,14 @@ public abstract class BaseXSSFFormulaEvaluator implements FormulaEvaluator, Work
      *  the result of the formula, use {@link #evaluate(org.apache.poi.ss.usermodel.Cell)} }
      * @param cell The cell to evaluate
      * @return The type of the formula result (the cell's type remains as CellType.FORMULA however)
+     *         If cell is not a formula cell, returns {@link CellType#_NONE} rather than throwing an exception.
+     * @since POI 3.15 beta 3
      * @deprecated POI 3.15 beta 3. Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     public CellType evaluateFormulaCellEnum(Cell cell) {
         if (cell == null || cell.getCellTypeEnum() != CellType.FORMULA) {
-            return CellType._UNINITIALIZED;
+            return CellType._NONE;
         }
         CellValue cv = evaluateFormulaCellValue(cell);
         // cell remains a formula cell, but the cached value is changed

src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java

@@ -682,7 +682,7 @@ public final class XSSFCell implements Cell {
      * @deprecated POI 3.15 beta 3
      * Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     @Override
     public CellType getCellTypeEnum() {
         if (isFormulaCell()) return CellType.FORMULA;
@@ -714,7 +714,7 @@ public final class XSSFCell implements Cell {
      * @deprecated POI 3.15 beta 3
      * Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     @Override
     public CellType getCachedFormulaResultTypeEnum() {
         if (! isFormulaCell()) {

src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFEvaluationCell.java

@@ -68,7 +68,7 @@ final class XSSFEvaluationCell implements EvaluationCell {
 	 * @deprecated POI 3.15 beta 3.
 	 * Will be deleted when we make the CellType enum transition. See bug 59791.
 	 */
-	@Internal
+	@Internal(since="POI 3.15 beta 3")
 	@Override
 	public CellType getCellTypeEnum() {
 		return _cell.getCellTypeEnum();
@@ -112,7 +112,7 @@ final class XSSFEvaluationCell implements EvaluationCell {
 	 * @deprecated POI 3.15 beta 3.
 	 * Will be deleted when we make the CellType enum transition. See bug 59791.
 	 */
-	@Internal
+	@Internal(since="POI 3.15 beta 3")
 	@Override
 	public CellType getCachedFormulaResultTypeEnum() {
 		return _cell.getCachedFormulaResultTypeEnum();

src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFTable.java

@@ -117,7 +117,7 @@ public class XSSFTable extends POIXMLDocumentPart implements Table {
     /**
       * get the underlying CTTable XML bean
       */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     public CTTable getCTTable() {
         return ctTable;
     }

src/ooxml/testcases/org/apache/poi/xssf/usermodel/TestXSSFBugs.java

@@ -2959,7 +2959,7 @@ public final class TestXSSFBugs extends BaseTestBugzillaIssues {
         cell = row.getCell(1);
 
         assertEquals(CellType.BLANK, cell.getCellTypeEnum());
-        assertEquals(CellType._UNINITIALIZED, evaluator.evaluateFormulaCellEnum(cell));
+        assertEquals(CellType._NONE, evaluator.evaluateFormulaCellEnum(cell));
 
         // A3
         row = worksheet.getRow(2);