From: Nick Burch <nick@apache.org>
Date: Wed, 12 Aug 2015 14:14:12 +0000 (+0000)
Subject: #58220 - Improve the javadocs for XSSFFont and Font getFontHeight methods
X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=6d46fc382ffdeddf76fa69bfe111fde1ca1edb60;p=poi.git

#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 4ddf474e43..a145f132a2 100644
--- 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 e9381b4289..28ef261ae9 100644
--- 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;
     }
 
     /**