javadocs fixes (jdk8)

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

src/java/org/apache/poi/hssf/model/DrawingManager2.java

@@ -45,6 +45,11 @@ public class DrawingManager2
     	drawingGroups.clear(); 
     }
 
+    /**
+     * Creates a new drawing group 
+     *
+     * @return a new drawing group
+     */
     public EscherDgRecord createDgRecord()
     {
         EscherDgRecord dg = new EscherDgRecord();
@@ -60,9 +65,11 @@ public class DrawingManager2
     }
 
     /**
-     * Allocates new shape id for the new drawing group id.
+     * Allocates new shape id for the drawing group id.
      * 
-     * @return a new shape id.
+     * @param drawingGroupId the drawing group id
+     * 
+     * @return a new shape id
      */
     public int allocateShapeId(short drawingGroupId)
     {
@@ -71,7 +78,10 @@ public class DrawingManager2
     }
 
     /**
-     * Allocates new shape id for the new drawing group id.
+     * Allocates new shape id for the drawing group
+     *
+     * @param drawingGroupId the drawing group id
+     * @param dg the EscherDgRecord which receives the new shape
      *
      * @return a new shape id.
      */
@@ -109,6 +119,8 @@ public class DrawingManager2
     
     /**
      * Finds the next available (1 based) drawing group id
+     * 
+     * @return the next available drawing group id
      */
     public short findNewDrawingGroupId()
     {
@@ -140,11 +152,19 @@ public class DrawingManager2
         return next;
     }
 
+    /**
+     * Returns the drawing group container record
+     *
+     * @return the drawing group container record
+     */
     public EscherDggRecord getDgg()
     {
         return dgg;
     }
 
+    /**
+     * Increment the drawing counter
+     */
     public void incrementDrawingsSaved(){
         dgg.setDrawingsSaved(dgg.getDrawingsSaved()+1);
     }

src/java/org/apache/poi/hssf/model/InternalSheet.java

@@ -87,7 +87,6 @@ import org.apache.poi.util.POILogger;
  * really know what you're doing.  I recommend you read the Microsoft Excel 97 Developer's
  * Kit (Microsoft Press) and the documentation at http://sc.openoffice.org/excelfileformat.pdf
  * before even attempting to use this.
- * <P>
  *
  * @see org.apache.poi.hssf.model.InternalWorkbook
  * @see org.apache.poi.hssf.usermodel.HSSFSheet
@@ -410,6 +409,8 @@ public final class InternalSheet {
      * can be added to a sheet. The <b>Record</b> object does not implement cloneable.
      * When adding a new record, implement a public clone method if and only if the record
      * belongs to a sheet.
+     * 
+     * @return the cloned sheet
      */
     public InternalSheet cloneSheet() {
         List<Record> clonedRecords = new ArrayList<Record>(_records.size());
@@ -512,6 +513,8 @@ public final class InternalSheet {
 
     /**
      * Updates formulas in cells and conditional formats due to moving of cells
+     * 
+     * @param shifter the formular shifter
      * @param externSheetIndex the externSheet index of this sheet
      */
     public void updateFormulasAfterCellShift(FormulaShifter shifter, int externSheetIndex) {
@@ -572,10 +575,14 @@ public final class InternalSheet {
      * sets the values in the sheet's DimensionsRecord object to be correct.  Excel doesn't
      * really care, but we want to play nice with other libraries.
      *
+     * @param firstrow the first row index
+     * @param firstcol the first column index
+     * @param lastrow the last row index
+     * @param lastcol the last column index
+     *
      * @see org.apache.poi.hssf.record.DimensionsRecord
      */
-    public void setDimensions(int firstrow, short firstcol, int lastrow,
+    public void setDimensions(int firstrow, short firstcol, int lastrow, short lastcol)
-                              short lastcol)
     {
         if (log.check( POILogger.DEBUG ))
         {
@@ -1023,6 +1030,8 @@ public final class InternalSheet {
 
     /**
      * set the default row height for the sheet (if the rows do not define their own height)
+     * 
+     * @param dch the default row height
      */
     public void setDefaultRowHeight(short dch) {
         defaultrowheight.setRowHeight(dch);
@@ -1066,7 +1075,7 @@ public final class InternalSheet {
      * Returns the index to the default ExtendedFormatRecord (0xF)
      * if no ColumnInfoRecord exists that includes the column
      * index specified.
-     * @param columnIndex
+     * @param columnIndex the column index
      * @return index of ExtendedFormatRecord associated with
      * ColumnInfoRecord that includes the column index or the
      * index of the default ExtendedFormatRecord (0xF)
@@ -1273,6 +1282,8 @@ public final class InternalSheet {
 
     /**
      * Gets the gridset record for this sheet.
+     * 
+     * @return the gridset record for this sheet
      */
     public GridsetRecord getGridsetRecord()
     {
@@ -1281,6 +1292,10 @@ public final class InternalSheet {
 
     /**
      * Returns the first occurrence of a record matching a particular sid.
+     * 
+     * @param sid the sid to search for
+     * 
+     * @return the matching record or {@code null} if it wasn't found
      */
     public Record findFirstRecordBySid(short sid) {
         int ix = findFirstRecordLocBySid(sid);

src/java/org/apache/poi/hssf/model/InternalWorkbook.java

@@ -372,6 +372,8 @@ public final class InternalWorkbook {
     /**
      * Creates an empty workbook object with three blank sheets and all the empty
      * fields.  Use this to create a workbook from scratch.
+     * 
+     * @return an empty workbook object
      */
     public static InternalWorkbook createWorkbook()
     {
@@ -508,6 +510,12 @@ public final class InternalWorkbook {
 
     /**
      * Retrieves the index of the given font
+     * 
+     * @param font the font
+     * 
+     * @return the font index
+     * 
+     * @throws IllegalArgumentException if the font index can't be determined 
      */
     public int getFontIndex(FontRecord font) {
         for(int i=0; i<=numfonts; i++) {
@@ -546,6 +554,8 @@ public final class InternalWorkbook {
      *  file's list. This will make all
      *  subsequent font indicies drop by one,
      *  so you'll need to update those yourself!
+     * 
+     * @param rec the font record
      */
     public void removeFontRecord(FontRecord rec) {
         records.remove(rec); // this updates FontPos for us
@@ -584,8 +594,9 @@ public final class InternalWorkbook {
 
     /**
      * Returns the position of the backup record.
+     * 
+     * @return the position of the backup record
      */
-
     public BackupRecord getBackupRecord() {
         return ( BackupRecord ) records.get(records.getBackuppos());
     }
@@ -873,6 +884,8 @@ public final class InternalWorkbook {
      *  file's list. This will make all
      *  subsequent font indicies drop by one,
      *  so you'll need to update those yourself!
+     * 
+     * @param rec the ExtendedFormatRecord
      */
     public void removeExFormatRecord(ExtendedFormatRecord rec) {
         records.remove(rec); // this updates XfPos for us
@@ -913,6 +926,10 @@ public final class InternalWorkbook {
      * Returns the StyleRecord for the given
      *  xfIndex, or null if that ExtendedFormat doesn't
      *  have a Style set.
+     *  
+     * @param xfIndex the extended format index
+     * 
+     * @return the StyleRecord, {@code null} if it that ExtendedFormat doesn't have a Style set.
      */
     public StyleRecord getStyleRecord(int xfIndex) {
         // Style records always follow after
@@ -932,10 +949,15 @@ public final class InternalWorkbook {
         }
         return null;
     }
+    
     /**
      * Creates a new StyleRecord, for the given Extended
      *  Format index, and adds it onto the end of the
      *  records collection
+     * 
+     * @param xfIndex the extended format index
+     * 
+     * @return a new StyleRecord
      */
     public StyleRecord createStyleRecord(int xfIndex) {
         // Style records always follow after
@@ -984,9 +1006,9 @@ public final class InternalWorkbook {
 
     /**
      * given an index into the SST table, this function returns the corresponding String value
+     * @param str the index into the SST table
      * @return String containing the SST String
      */
-
     public UnicodeString getSSTString(int str) {
         if (sst == null) {
             insertSST();
@@ -1047,8 +1069,8 @@ public final class InternalWorkbook {
      * this to write the Workbook out.
      * @param offset of the data to be written
      * @param data array of bytes to write this to
+     * @return the length of serialized bytes
      */
-
     public int serialize( int offset, byte[] data )
     {
         if (log.check( POILogger.DEBUG ))
@@ -1947,7 +1969,8 @@ public final class InternalWorkbook {
         return linkTable.getNumNames();
     }
 
-    /** gets the name record
+    /**
+     * gets the name record
      * @param index name index
      * @return name record
      */
@@ -1955,7 +1978,8 @@ public final class InternalWorkbook {
         return linkTable.getNameRecord(index);
     }
 
-    /** gets the name comment record
+    /**
+     * gets the name comment record
      * @param nameRecord name record who's comment is required.
      * @return name comment record or <code>null</code> if there isn't one for the given name.
      */
@@ -1963,7 +1987,8 @@ public final class InternalWorkbook {
         return commentRecords.get(nameRecord.getNameText());
     }
 
-    /** creates new name
+    /**
+     * creates new name
      * @return new name record
      */
     public NameRecord createName(){
@@ -1971,8 +1996,11 @@ public final class InternalWorkbook {
     }
 
 
-    /** creates new name
+    /**
-     * @return new name record
+     * adds a name record
+     * 
+     * @param name the name record to be added
+     * @return the given name record 
      */
     public NameRecord addName(NameRecord name)
     {
@@ -1985,6 +2013,10 @@ public final class InternalWorkbook {
 
     /**
      * Generates a NameRecord to represent a built-in region
+     * 
+     * @param builtInName the built-in name
+     * @param sheetNumber the sheet number
+     * 
      * @return a new NameRecord
      */
     public NameRecord createBuiltInName(byte builtInName, int sheetNumber) {
@@ -2018,6 +2050,8 @@ public final class InternalWorkbook {
     /**
      * If a {@link NameCommentRecord} is added or the name it references
      *  is renamed, then this will update the lookup cache for it.
+     * 
+     * @param commentRecord the comment record
      */
     public void updateNameCommentRecordCache(final NameCommentRecord commentRecord) {
        if(commentRecords.containsValue(commentRecord)) {
@@ -2084,6 +2118,10 @@ public final class InternalWorkbook {
 
     /**
      * Returns the first occurance of a record matching a particular sid.
+     * 
+     * @param sid the sid
+     * 
+     * @return the matching record or {@code null} if it wasn't found
      */
     public Record findFirstRecordBySid(short sid) {
         for (Record record : records) {
@@ -2112,6 +2150,11 @@ public final class InternalWorkbook {
 
     /**
      * Returns the next occurance of a record matching a particular sid.
+     * 
+     * @param sid the sid
+     * @param pos specifies the n-th matching sid
+     * 
+     * @return the matching record or {@code null} if it wasn't found
      */
     public Record findNextRecordBySid(short sid, int pos) {
         int matches = 0;
@@ -2146,6 +2189,8 @@ public final class InternalWorkbook {
     /**
      * Returns the custom palette in use for this workbook; if a custom palette record
      * does not exist, then it is created.
+     * 
+     * @return the custom palette
      */
     public PaletteRecord getCustomPalette()
     {
@@ -2169,6 +2214,8 @@ public final class InternalWorkbook {
 
     /**
      * Finds the primary drawing group, if one already exists
+     * 
+     * @return the primary drawing group
      */
     public DrawingManager2 findDrawingGroup() {
         if(drawingManager != null) {
@@ -2388,6 +2435,8 @@ public final class InternalWorkbook {
 
     /**
      * is the workbook protected with a password (not encrypted)?
+     * 
+     * @return {@code true} if the workbook is write protected
      */
     public boolean isWriteProtected() {
         if (fileShare == null) {
@@ -2400,7 +2449,9 @@ public final class InternalWorkbook {
     /**
      * protect a workbook with a password (not encypted, just sets writeprotect
      * flags and the password.
-     * @param password to set
+     * 
+     * @param password the password
+     * @param username the username
      */
     public void writeProtectWorkbook( String password, String username ) {
         FileSharingRecord frec = getFileSharing();
@@ -2549,6 +2600,8 @@ public final class InternalWorkbook {
     }
     /**
      * Updates named ranges due to moving of cells
+     * 
+     * @param shifter the formula shifter
      */
     public void updateNamesAfterCellShift(FormulaShifter shifter) {
         for (int i = 0 ; i < getNumNames() ; ++i){
@@ -2563,6 +2616,8 @@ public final class InternalWorkbook {
     /**
      * Get or create RecalcIdRecord
      *
+     * @return a new RecalcIdRecord
+     *
      * @see org.apache.poi.hssf.usermodel.HSSFWorkbook#setForceFormulaRecalculation(boolean)
      */
     public RecalcIdRecord getRecalcId(){