Improve javadocs for new code in Type3Font handling

DEVSIX-5199

Autoported commit.
Original commit hash: [8a77dd3dc]

Author: yulian-gaponenko

itext/itext.kernel/itext/kernel/font/PdfFont.cs

@@ -200,7 +200,10 @@ public virtual bool AppendDecodedCodesToGlyphsList(IList<Glyph> list, PdfString
 
         public abstract void WriteText(String text, PdfOutputStream stream);
 
-        [Obsolete]
+        /// <summary>Gets the transformation matrix that defines relation between text and glyph spaces.</summary>
+        /// <returns>the font matrix</returns>
+        [System.ObsoleteAttribute(@"Use iText.IO.Font.FontProgram.UNITS_NORMALIZATION constant for conversion between text and glyph space. For now we opted to always expect that all 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 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."
+            )]
         public virtual double[] GetFontMatrix() {
             return DEFAULT_FONT_MATRIX;
         }

itext/itext.kernel/itext/kernel/font/PdfSimpleFont.cs

@@ -518,7 +518,11 @@ protected internal virtual void SetFontProgram(T fontProgram) {
             this.fontProgram = fontProgram;
         }
 
-        [Obsolete]
+        /// <summary>Gets glyph width which us ready to be written to the output file.</summary>
+        /// <param name="glyph">the glyph which widths is required to be written to the output file</param>
+        /// <returns>glyph width in glyph-space</returns>
+        [System.ObsoleteAttribute(@"This method was introduced to allow overriding of widths array entry writing to output file. It's now replaced by more specific PdfSimpleFont{T}.BuildWidthsArray(int, int) in order to avoid confusion between this method and iText.IO.Font.Otf.Glyph.GetWidth() . This method will be removed in the next major release."
+            )]
         protected internal virtual double GetGlyphWidth(Glyph glyph) {
             return glyph != null ? glyph.GetWidth() : 0;
         }

itext/itext.kernel/itext/kernel/font/Type3Font.cs

@@ -145,14 +145,14 @@ public virtual int GetNumberOfGlyphs() {
         /// </remarks>
         /// <param name="fontName">the PostScript name of the font, shall not be null or empty.</param>
         protected internal override 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.
             base.SetFontName(fontName);
         }
 
         /// <summary>Sets a preferred font family name.</summary>
         /// <param name="fontFamily">a preferred font family name.</param>
         protected internal override 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.
             base.SetFontFamily(fontFamily);
         }
 
@@ -162,7 +162,7 @@ protected internal override void SetFontFamily(String fontFamily) {
         /// <see cref="iText.IO.Font.Constants.FontWeights"/>.
         /// </param>
         protected internal override 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.
             base.SetFontWeight(fontWeight);
         }
 
@@ -172,31 +172,31 @@ protected internal override void SetFontWeight(int fontWeight) {
         /// <see cref="iText.IO.Font.Constants.FontStretches"/>.
         /// </param>
         protected internal override 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.
             base.SetFontStretch(fontWidth);
         }
 
         /// <summary><inheritDoc/></summary>
         protected internal override 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.
             base.SetCapHeight(capHeight);
         }
 
         /// <summary><inheritDoc/></summary>
         protected internal override 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.
             base.SetItalicAngle(italicAngle);
         }
 
         /// <summary><inheritDoc/></summary>
         protected internal override 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.
             base.SetTypoAscender(ascender);
         }
 
         /// <summary><inheritDoc/></summary>
         protected internal override 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.
             base.SetTypoDescender(descender);
         }
 

port-hash

@@ -1 +1 @@
-c72ff11f48c00ff895ba747c0a1cbeeaffdf66e1
+8a77dd3dc42cfe5f07b3bc59e15c3aa04a3e0c7a