Update javadoc in FontProgramFactory and PdfFontFactory

Author: pavel-alay

io/src/main/java/com/itextpdf/io/font/FontProgramFactory.java

@@ -73,7 +73,7 @@ private FontProgramFactory() {
      * Creates a new standard Helvetica font program file.
      *
      * @return a {@link FontProgram} object with Helvetica font description
-     * @throws java.io.IOException
+     * @throws java.io.IOException exception is thrown in case an I/O error occurs when reading the file
      */
     public static FontProgram createFont() throws java.io.IOException {
         return createFont(StandardFonts.HELVETICA);
@@ -92,7 +92,7 @@ public static FontProgram createFont() throws java.io.IOException {
      *
      * @param fontProgram the name of the font or its location on file
      * @return returns a new {@link FontProgram}. This font program may come from the cache
-     * @throws java.io.IOException
+     * @throws java.io.IOException exception is thrown in case an I/O error occurs when reading the file
      */
     public static FontProgram createFont(String fontProgram) throws java.io.IOException {
         return createFont(fontProgram, null, DEFAULT_CACHED);
@@ -112,7 +112,7 @@ public static FontProgram createFont(String fontProgram) throws java.io.IOExcept
      * @param fontProgram the name of the font or its location on file
      * @param cached whether to to cache this font program after it has been loaded
      * @return returns a new {@link FontProgram}. This font program may come from the cache
-     * @throws java.io.IOException
+     * @throws java.io.IOException exception is thrown in case an I/O error occurs when reading the file
      */
     public static FontProgram createFont(String fontProgram, boolean cached) throws java.io.IOException {
         return createFont(fontProgram, null, cached);
@@ -131,7 +131,7 @@ public static FontProgram createFont(String fontProgram, boolean cached) throws
      *
      * @param fontProgram the byte contents of the font program
      * @return returns a new {@link FontProgram}. This font program may come from the cache
-     * @throws java.io.IOException
+     * @throws java.io.IOException exception is thrown in case an I/O error occurs when reading the file
      */
     public static FontProgram createFont(byte[] fontProgram) throws java.io.IOException {
         return createFont(null, fontProgram, DEFAULT_CACHED);
@@ -151,7 +151,7 @@ public static FontProgram createFont(byte[] fontProgram) throws java.io.IOExcept
      * @param fontProgram the byte contents of the font program
      * @param cached whether to to cache this font program
      * @return returns a new {@link FontProgram}. This font program may come from the cache
-     * @throws java.io.IOException
+     * @throws java.io.IOException exception is thrown in case an I/O error occurs when reading the file
      */
     public static FontProgram createFont(byte[] fontProgram, boolean cached) throws java.io.IOException {
         return createFont(null, fontProgram, cached);
@@ -256,7 +256,7 @@ private static FontProgram createFont(String name, byte[] fontProgram, boolean c
      * @param afm the contents of the AFM or PFM metrics file
      * @param pfb the contents of the PFB file
      * @return created {@link FontProgram} instance
-     * @throws java.io.IOException
+     * @throws java.io.IOException exception is thrown in case an I/O error occurs when reading the file
      */
     public static FontProgram createType1Font(byte[] afm, byte[] pfb) throws java.io.IOException {
         return createType1Font(afm, pfb, DEFAULT_CACHED);
@@ -269,7 +269,7 @@ public static FontProgram createType1Font(byte[] afm, byte[] pfb) throws java.io
      * @param pfb the contents of the PFB file
      * @param cached specifies whether to cache the created {@link FontProgram} or not
      * @return created {@link FontProgram} instance
-     * @throws java.io.IOException
+     * @throws java.io.IOException exception is thrown in case an I/O error occurs when reading the file
      */
     public static FontProgram createType1Font(byte[] afm, byte[] pfb, boolean cached) throws java.io.IOException {
         return createType1Font(null, null, afm, pfb, cached);
@@ -281,7 +281,7 @@ public static FontProgram createType1Font(byte[] afm, byte[] pfb, boolean cached
      * @param metricsPath path to the AFM or PFM metrics file
      * @param binaryPath path to the contents of the PFB file
      * @return created {@link FontProgram} instance
-     * @throws java.io.IOException
+     * @throws java.io.IOException exception is thrown in case an I/O error occurs when reading the file
      */
     public static FontProgram createType1Font(String metricsPath, String binaryPath) throws java.io.IOException {
         return createType1Font(metricsPath, binaryPath, DEFAULT_CACHED);
@@ -294,7 +294,7 @@ public static FontProgram createType1Font(String metricsPath, String binaryPath)
      * @param binaryPath path to the contents of the PFB file
      * @param cached specifies whether to cache the created {@link FontProgram} or not
      * @return created {@link FontProgram} instance
-     * @throws java.io.IOException
+     * @throws java.io.IOException exception is thrown in case an I/O error occurs when reading the file
      */
     public static FontProgram createType1Font(String metricsPath, String binaryPath, boolean cached) throws java.io.IOException {
         return createType1Font(metricsPath, binaryPath, null, null, cached);
@@ -309,7 +309,7 @@ public static FontProgram createType1Font(String metricsPath, String binaryPath,
      *                 the cache if new, false if the font is always created new
      * @return returns a new {@link FontProgram} instance. This font may come from the cache but only if cached
      * is true, otherwise it will always be created new
-     * @throws java.io.IOException
+     * @throws java.io.IOException exception is thrown in case an I/O error occurs when reading the file
      */
     public static FontProgram createFont(String ttc, int ttcIndex, boolean cached) throws java.io.IOException {
         FontCacheKey fontCacheKey = FontCacheKey.create(ttc, ttcIndex);
@@ -332,7 +332,7 @@ public static FontProgram createFont(String ttc, int ttcIndex, boolean cached) t
      *                 the cache if new, false if the font is always created new
      * @return returns a new {@link FontProgram} instance. This font may come from the cache but only if cached
      * is true, otherwise it will always be created new
-     * @throws java.io.IOException
+     * @throws java.io.IOException exception is thrown in case an I/O error occurs when reading the file
      */
     public static FontProgram createFont(byte[] ttc, int ttcIndex, boolean cached) throws java.io.IOException {
         FontCacheKey fontKey = FontCacheKey.create(ttc, ttcIndex);
@@ -356,7 +356,7 @@ public static FontProgram createFont(byte[] ttc, int ttcIndex, boolean cached) t
      *              {@link FontStyles#BOLDITALIC}, {@link FontStyles#UNDEFINED}
      * @param cached whether to try to get the font program from cache
      * @return created {@link FontProgram}
-     * @throws java.io.IOException
+     * @throws java.io.IOException exception is thrown in case an I/O error occurs when reading the file
      */
     public static FontProgram createRegisteredFont(String fontName, int style, boolean cached) throws java.io.IOException {
         return fontRegisterProvider.getFont(fontName, style, cached);
@@ -371,7 +371,7 @@ public static FontProgram createRegisteredFont(String fontName, int style, boole
      *              See {@link FontStyles#BOLD}, {@link FontStyles#ITALIC}, {@link FontStyles#NORMAL},
      *              {@link FontStyles#BOLDITALIC}, {@link FontStyles#UNDEFINED}
      * @return created {@link FontProgram}
-     * @throws java.io.IOException
+     * @throws java.io.IOException exception is thrown in case an I/O error occurs when reading the file
      */
     public static FontProgram createRegisteredFont(String fontName, int style) throws java.io.IOException {
         return fontRegisterProvider.getFont(fontName, style);
@@ -383,7 +383,7 @@ public static FontProgram createRegisteredFont(String fontName, int style) throw
      * @param fontName either a font alias, if the font file has been registered with an alias,
      *                 or just a font name otherwise
      * @return created {@link FontProgram}
-     * @throws java.io.IOException
+     * @throws java.io.IOException exception is thrown in case an I/O error occurs when reading the file2
      */
     public static FontProgram createRegisteredFont(String fontName) throws java.io.IOException {
         return fontRegisterProvider.getFont(fontName, FontStyles.UNDEFINED);
@@ -496,6 +496,9 @@ private static FontCacheKey createFontCacheKey(String name, byte[] fontProgram)
 
     public static void clearRegisteredFonts() { fontRegisterProvider.clearRegisteredFonts(); }
 
+    /**
+     * Clears registered font cache
+     */
     public static void clearRegisteredFontFamilies() { fontRegisterProvider.clearRegisteredFontFamilies(); }
 
     static byte[] readFontBytesFromPath(String path) throws java.io.IOException {

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

@@ -61,7 +61,7 @@ This file is part of the iText (R) project.
 
 /**
  * This class provides helpful methods for creating fonts ready to be used in a {@link PdfDocument}
- *
+ * <p>
  * Note, just created {@link PdfFont} is almost empty until it will be flushed,
  * because it is impossible to fulfill font data until flush.
  */
@@ -95,12 +95,12 @@ public static PdfFont createFont() throws IOException {
 
     /**
      * Creates a {@link PdfFont} by already existing font dictionary.
-     *
+     * <p>
      * Note, the font won't be added to any document,
      * until you add it to {@link com.itextpdf.kernel.pdf.canvas.PdfCanvas}.
      * While adding to {@link com.itextpdf.kernel.pdf.canvas.PdfCanvas}, or to
      * {@link com.itextpdf.kernel.pdf.PdfResources} the font will be made indirect implicitly.
-     *
+     * <p>
      * {@link PdfDocument#getFont} method is strongly recommended if you want to get PdfFont by both
      * existing font dictionary, or just created and hasn't flushed yet.
      *
@@ -290,7 +290,7 @@ public static PdfFont createFont(FontProgram fontProgram) {
      * Created a {@link PdfFont} instance by the bytes of the underlying font program.
      *
      * @param fontProgram the bytes of the underlying font program
-     * @param encoding
+     * @param encoding    the encoding of the font to be created. See {@link PdfEncodings}
      * @return created {@link PdfFont} instance
      * @throws IOException signals that an I/O exception has occurred.
      */
@@ -365,12 +365,12 @@ public static PdfType3Font createType3Font(PdfDocument document, String fontName
     /**
      * Creates {@link PdfFont} based on registered {@link FontProgram}'s.
      *
-     * @param fontName
-     * @param encoding
-     * @param embedded
-     * @param style
-     * @param cached
-     * @throws IOException
+     * @param fontName Path to font file or Standard font name
+     * @param encoding Font encoding from {@link PdfEncodings}.
+     * @param embedded if true font will be embedded. Note, standard font won't be embedded in any case.
+     * @param style    Font style from {@link FontStyles}.
+     * @param cached   If true font will be cached for another PdfDocument
+     * @throws IOException exception is thrown in case an I/O error occurs when reading the file
      * @see PdfFontFactory#register(String)
      * @see PdfFontFactory#register(String, String)
      * @see PdfFontFactory#registerFamily(String, String, String)
@@ -387,11 +387,11 @@ public static PdfFont createRegisteredFont(String fontName, String encoding, boo
     /**
      * Creates {@link PdfFont} based on registered {@link FontProgram}'s.
      *
-     * @param fontName
-     * @param encoding
-     * @param embedded
-     * @param cached
-     * @throws IOException
+     * @param fontName Path to font file or Standard font name
+     * @param encoding Font encoding from {@link PdfEncodings}.
+     * @param embedded if true font will be embedded. Note, standard font won't be embedded in any case.
+     * @param cached   If true font will be cached for another PdfDocument
+     * @throws IOException exception is thrown in case an I/O error occurs when reading the file
      * @see PdfFontFactory#register(String)
      * @see PdfFontFactory#register(String, String)
      * @see PdfFontFactory#registerFamily(String, String, String)
@@ -407,10 +407,10 @@ public static PdfFont createRegisteredFont(String fontName, String encoding, boo
     /**
      * Creates {@link PdfFont} based on registered {@link FontProgram}'s.
      *
-     * @param fontName
-     * @param encoding
-     * @param embedded
-     * @throws IOException
+     * @param fontName Path to font file or Standard font name
+     * @param encoding Font encoding from {@link PdfEncodings}.
+     * @param embedded if true font will be embedded. Note, standard font won't be embedded in any case.
+     * @throws IOException exception is thrown in case an I/O error occurs when reading the file
      * @see PdfFontFactory#register(String)
      * @see PdfFontFactory#register(String, String)
      * @see PdfFontFactory#registerFamily(String, String, String)
@@ -426,11 +426,11 @@ public static PdfFont createRegisteredFont(String fontName, String encoding, boo
     /**
      * Creates {@link PdfFont} based on registered {@link FontProgram}'s.
      *
-     * @param fontName
-     * @param encoding
-     * @param embedded
-     * @param style
-     * @throws IOException
+     * @param fontName Path to font file or Standard font name
+     * @param encoding Font encoding from {@link PdfEncodings}.
+     * @param embedded if true font will be embedded. Note, standard font won't be embedded in any case.
+     * @param style    Font style from {@link FontStyles}.
+     * @throws IOException exception is thrown in case an I/O error occurs when reading the file
      * @see PdfFontFactory#register(String)
      * @see PdfFontFactory#register(String, String)
      * @see PdfFontFactory#registerFamily(String, String, String)
@@ -446,9 +446,9 @@ public static PdfFont createRegisteredFont(String fontName, String encoding, boo
     /**
      * Creates {@link PdfFont} based on registered {@link FontProgram}'s.
      *
-     * @param fontName
-     * @param encoding
-     * @throws IOException
+     * @param fontName Path to font file or Standard font name
+     * @param encoding Font encoding from {@link PdfEncodings}.
+     * @throws IOException exception is thrown in case an I/O error occurs when reading the file
      * @see PdfFontFactory#register(String)
      * @see PdfFontFactory#register(String, String)
      * @see PdfFontFactory#registerFamily(String, String, String)
@@ -464,8 +464,8 @@ public static PdfFont createRegisteredFont(String fontName, String encoding) thr
     /**
      * Creates {@link PdfFont} based on registered {@link FontProgram}'s.
      *
-     * @param fontName
-     * @throws IOException
+     * @param fontName Path to font file or Standard font name
+     * @throws IOException exception is thrown in case an I/O error occurs when reading the file
      * @see PdfFontFactory#register(String)
      * @see PdfFontFactory#register(String, String)
      * @see PdfFontFactory#registerFamily(String, String, String)