bug 58775: add Override annotations, Javadocs, and comments

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

src/ooxml/java/org/apache/poi/xssf/model/StylesTable.java

@@ -210,6 +210,14 @@ public class StylesTable extends POIXMLDocumentPart {
         return numberFormats.get(idx);
     }
 
+    /**
+     * Puts <code>fmt</code> in the numberFormats map if the format is not
+     * already in the the number format style table.
+     * Does nothing if <code>fmt</code> is already in number format style table.
+     *
+     * @param fmt the number format to add to number format style table
+     * @return the index of <code>fmt</code> in the number format style table
+     */
     public int putNumberFormat(String fmt) {
         if (numberFormats.containsValue(fmt)) {
             // Find the key, and return that

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

@@ -23,9 +23,16 @@ import org.apache.poi.xssf.model.StylesTable;
 /**
  * Handles data formats for XSSF.
  * 
+ * Per Microsoft Excel 2007+ format limitations:
+ * Workbooks support between 200 and 250 "number formats"
+ * (POI calls them "data formats") So short or even byte
+ * would be acceptable data types to use for referring to
+ * data format indices.
+ * https://support.office.com/en-us/article/excel-specifications-and-limits-1672b34d-7043-467e-8e27-269d656771c3
+ * 
  */
 public class XSSFDataFormat implements DataFormat {
-    private StylesTable stylesSource;
+    private final StylesTable stylesSource;
 
     protected XSSFDataFormat(StylesTable stylesSource) {
         this.stylesSource = stylesSource;
@@ -36,9 +43,10 @@ public class XSSFDataFormat implements DataFormat {
      *  string, creating a new format entry if required.
      * Aliases text to the proper format as required.
      *
-     * @param format string matching a built in format
+     * @param format string matching a built-in format
      * @return index of format.
      */
+    @Override
     public short getFormat(String format) {
         int idx = BuiltinFormats.getBuiltinFormat(format);
         if(idx == -1) idx = stylesSource.putNumberFormat(format);
@@ -48,17 +56,24 @@ public class XSSFDataFormat implements DataFormat {
     /**
      * get the format string that matches the given format index
      * @param index of a format
-     * @return string represented at index of format or null if there is not a  format at that index
+     * @return string represented at index of format or <code>null</code> if there is not a  format at that index
      */
+    @Override
     public String getFormat(short index) {
         return getFormat(index&0xffff);
     }
     /**
      * get the format string that matches the given format index
      * @param index of a format
-     * @return string represented at index of format or null if there is not a  format at that index
+     * @return string represented at index of format or <code>null</code> if there is not a  format at that index
      */
     public String getFormat(int index) {
+        // Indices used for built-in formats may be overridden with
+        // custom formats, such as locale-specific currency.
+        // See org.apache.poi.xssf.usermodel.TestXSSFDataFormat#test49928() 
+        // or bug 49928 for an example.
+        // This is why we need to check stylesSource first and only fall back to
+        // BuiltinFormats if the format hasn't been overridden.
         String fmt = stylesSource.getNumberFormatAt(index);
         if(fmt == null) fmt = BuiltinFormats.getBuiltinFormat(index);
         return fmt;

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

@@ -660,7 +660,7 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook {
     }
 
     /**
-     * Returns the instance of XSSFDataFormat for this workbook.
+     * Returns the workbook's data format table (a factory for creating data format strings).
      *
      * @return the XSSFDataFormat object
      * @see org.apache.poi.ss.usermodel.DataFormat