#58220 - Improve the javadocs for XSSFFont and Font getFontHeight methods

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

diff --git a/src/java/org/apache/poi/ss/usermodel/Font.java b/src/java/org/apache/poi/ss/usermodel/Font.java
index 4ddf474e43962a3aed869e86b948beae636a62e3..a145f132a237e3b7ac2601b6704598a31fd1411b 100644 (file)
--- a/src/java/org/apache/poi/ss/usermodel/Font.java
+++ b/src/java/org/apache/poi/ss/usermodel/Font.java
@@ -138,20 +138,25 @@ public interface Font {
     void setFontHeightInPoints(short height);
 
     /**
-     * get the font height in unit's of 1/20th of a point.  Maybe you might want to
-     * use the getFontHeightInPoints which matches to the familiar 10, 12, 14 etc..
+     * Get the font height in unit's of 1/20th of a point.
+     * <p>
+     * For many users, the related {@link #getFontHeightInPoints()}
+     *  will be more helpful, as that returns font heights in the
+     *  more familiar points units, eg 10, 12, 14.
+
      * @return short - height in 1/20ths of a point
      * @see #getFontHeightInPoints()
      */
-
     short getFontHeight();
 
     /**
-     * get the font height
+     * Get the font height in points.
+     * <p>
+     * This will return the same font height that is shown in Excel,
+     *  such as 10 or 14 or 28.
      * @return short - height in the familiar unit of measure - points
      * @see #getFontHeight()
      */
-
     short getFontHeightInPoints();
 
     /**

diff --git a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFFont.java b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFFont.java
index e9381b428974b23c54bfdb4dd5eec6e0dd0699fc..28ef261ae9d9ada0fa26c504e6be6150473bb27b 100644 (file)
--- a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFFont.java
+++ b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFFont.java
@@ -174,24 +174,42 @@ public class XSSFFont implements Font {
     }
 
     /**
-     * get the font height in point.
-     *
-     * @return short - height in point
+     * Get the font height in unit's of 1/20th of a point.
+     * <p>
+     * For many users, the related {@link #getFontHeightInPoints()}
+     *  will be more helpful, as that returns font heights in the
+     *  more familiar points units, eg 10, 12, 14.
+
+     * @return short - height in 1/20ths of a point
+     * @see #getFontHeightInPoints()
      */
     public short getFontHeight() {
-        CTFontSize size = _ctFont.sizeOfSzArray() == 0 ? null : _ctFont.getSzArray(0);
-        if (size != null) {
-            double fontHeight = size.getVal();
-            return (short)(fontHeight*20);
-        }
-        return (short)(DEFAULT_FONT_SIZE*20);
+        return (short)(getFontHeightRaw()*20);
     }
 
     /**
+     * Get the font height in points.
+     * <p>
+     * This will return the same font height that is shown in Excel,
+     *  such as 10 or 14 or 28.
+     * @return short - height in the familiar unit of measure - points
      * @see #getFontHeight()
      */
     public short getFontHeightInPoints() {
-        return (short)(getFontHeight()/20);
+        return (short)getFontHeightRaw();
+    }
+    
+    /**
+     * Return the raw font height, in points, but also
+     *  including fractions.
+     */
+    private double getFontHeightRaw() {
+        CTFontSize size = _ctFont.sizeOfSzArray() == 0 ? null : _ctFont.getSzArray(0);
+        if (size != null) {
+            double fontHeight = size.getVal();
+            return fontHeight;
+        }
+        return DEFAULT_FONT_SIZE;
     }
 
     /**