Improve javadocs for new code in Type3Font handling

DEVSIX-5199

Author: yulian-gaponenko

kernel/src/main/java/com/itextpdf/kernel/font/PdfFont.java

@@ -210,6 +210,18 @@ public boolean appendDecodedCodesToGlyphsList(List<Glyph> list, PdfString charac
 
     public abstract void writeText(String text, PdfOutputStream stream);
 
+    /**
+     * Gets the transformation matrix that defines relation between text and glyph spaces.
+     *
+     * @return the font matrix
+     *
+     * @deprecated Use {@link FontProgram#UNITS_NORMALIZATION} constant for conversion between text and glyph space.
+     *         For now we opted to always expect that all {@link PdfFont} metrics in glyph-space
+     *         are related to text space as 1 to 1000, as it is defined for the majority of fonts. For fonts
+     *         which don't necessary follow this rule (see {@link PdfType3Font}), we perform internal normalization
+     *         of font metrics in order to adhere to this common expectation.
+     *         This method will be removed in next major release.
+     */
     @Deprecated
     public double[] getFontMatrix() {
         return DEFAULT_FONT_MATRIX;

kernel/src/main/java/com/itextpdf/kernel/font/PdfSimpleFont.java

@@ -524,6 +524,18 @@ protected void setFontProgram(T fontProgram) {
         this.fontProgram = fontProgram;
     }
 
+    /**
+     * Gets glyph width which us ready to be written to the output file.
+     *
+     * @param glyph the glyph which widths is required to be written to the output file
+     *
+     * @return glyph width in glyph-space
+     *
+     * @deprecated This method was introduced to allow overriding of widths array entry writing to
+     *         output file. It's now replaced by more specific {@link #buildWidthsArray(int, int)} in order to
+     *         avoid confusion between this method and {@link Glyph#getWidth()}.
+     *         This method will be removed in the next major release.
+     */
     @Deprecated
     protected double getGlyphWidth(Glyph glyph) {
         return glyph != null ? glyph.getWidth() : 0;

kernel/src/main/java/com/itextpdf/kernel/font/Type3Font.java

@@ -147,7 +147,7 @@ public int getNumberOfGlyphs() {
      */
     @Override
     protected void setFontName(String fontName) {
-        // This dummy override allows PdfType3Font to set font name from different module.
+        // This dummy override allows PdfType3Font to use setter from different module.
         super.setFontName(fontName);
     }
 
@@ -158,7 +158,7 @@ protected void setFontName(String fontName) {
      */
     @Override
     protected void setFontFamily(String fontFamily) {
-        // This dummy override allows PdfType3Font to set font name from different module.
+        // This dummy override allows PdfType3Font to use setter from different module.
         super.setFontFamily(fontFamily);
     }
 
@@ -169,7 +169,7 @@ protected void setFontFamily(String fontFamily) {
      */
     @Override
     protected void setFontWeight(int fontWeight) {
-        // This dummy override allows PdfType3Font to set font name from different module.
+        // This dummy override allows PdfType3Font to use setter from different module.
         super.setFontWeight(fontWeight);
     }
 
@@ -180,7 +180,7 @@ protected void setFontWeight(int fontWeight) {
      */
     @Override
     protected void setFontStretch(String fontWidth) {
-        // This dummy override allows PdfType3Font to set font name from different module.
+        // This dummy override allows PdfType3Font to use setter from different module.
         super.setFontStretch(fontWidth);
     }
 
@@ -189,7 +189,7 @@ protected void setFontStretch(String fontWidth) {
      */
     @Override
     protected void setCapHeight(int capHeight) {
-        // This dummy override allows PdfType3Font to set the PostScript italicAngle from different module.
+        // This dummy override allows PdfType3Font to use setter from different module.
         super.setCapHeight(capHeight);
     }
 
@@ -198,7 +198,7 @@ protected void setCapHeight(int capHeight) {
      */
     @Override
     protected void setItalicAngle(int italicAngle) {
-        // This dummy override allows PdfType3Font to set the PostScript italicAngle from different module.
+        // This dummy override allows PdfType3Font to use setter from different module.
         super.setItalicAngle(italicAngle);
     }
 
@@ -207,7 +207,7 @@ protected void setItalicAngle(int italicAngle) {
      */
     @Override
     protected void setTypoAscender(int ascender) {
-        // This dummy override allows PdfType3Font to set typoAscender from different module.
+        // This dummy override allows PdfType3Font to use setter from different module.
         super.setTypoAscender(ascender);
     }
 
@@ -216,7 +216,7 @@ protected void setTypoAscender(int ascender) {
      */
     @Override
     protected void setTypoDescender(int descender) {
-        // This dummy override allows PdfType3Font to set typoDescender from different module.
+        // This dummy override allows PdfType3Font to use setter from different module.
         super.setTypoDescender(descender);
     }
 

kernel/src/main/java/com/itextpdf/kernel/pdf/canvas/parser/data/TextRenderInfo.java

@@ -501,7 +501,7 @@ private float[] getWidthAndWordSpacing(PdfString string) {
         checkGraphicsState();
         float[] result = new float[2];
 
-        result[0] = (float) ((double)gs.getFont().getContentWidth(string) / FontProgram.UNITS_NORMALIZATION);
+        result[0] = (float) ((double) gs.getFont().getContentWidth(string) / FontProgram.UNITS_NORMALIZATION);
         result[1] = " ".equals(string.getValue()) ? gs.getWordSpacing() : 0;
         return result;
     }