#7 improve api documentation and make font descriptor public

src/UglyToad.PdfPig.Tests/PublicApiScannerTests.cs

@@ -46,6 +46,10 @@
                 "UglyToad.PdfPig.CrossReference.CrossReferenceTable",
                 "UglyToad.PdfPig.CrossReference.CrossReferenceType",
                 "UglyToad.PdfPig.CrossReference.TrailerDictionary",
+                "UglyToad.PdfPig.Fonts.DescriptorFontFile",
+                "UglyToad.PdfPig.Fonts.FontDescriptor",
+                "UglyToad.PdfPig.Fonts.FontDescriptorFlags",
+                "UglyToad.PdfPig.Fonts.FontStretch",
                 "UglyToad.PdfPig.Tokens.ArrayToken",
                 "UglyToad.PdfPig.Tokens.BooleanToken",
                 "UglyToad.PdfPig.Tokens.CommentToken",

src/UglyToad.PdfPig/Fonts/DescriptorFontFile.cs

@@ -3,7 +3,7 @@
     using Tokens;
 
     /// <summary>
-    /// The bytes of the stream containing the font program.
+    /// Holds the location and type of the stream containing the corresponding font program.
     /// </summary>
     /// <remarks>
     /// This can either be a Type 1 font program (FontFile - <see cref="FontFileType.Type1"/>),
@@ -11,25 +11,43 @@
     /// whose format is given by the Subtype of the stream dictionary (FontFile3 - <see cref="FontFileType.FromSubtype"/>).
     /// At most only 1 of these entries is present.
     /// </remarks>
-    internal class DescriptorFontFile
+    public class DescriptorFontFile
     {
+        /// <summary>
+        /// The object containing the stream for this font program.
+        /// </summary>
         public IndirectReferenceToken ObjectKey { get; }
-
+        
-        public byte[] FileBytes { get; }
+        /// <summary>
-
+        /// The type of the font program represented by this descriptor.
+        /// </summary>
         public FontFileType FileType { get; }
 
+        /// <summary>
+        /// Create a new <see cref="DescriptorFontFile"/>.
+        /// </summary>
         public DescriptorFontFile(IndirectReferenceToken key, FontFileType fileType)
         {
             ObjectKey = key;
-            FileBytes = new byte[0];
             FileType = fileType;
         }
 
+        /// <summary>
+        /// The type of font program represented by the stream used by this font descriptor.
+        /// </summary>
         public enum FontFileType
         {
+            /// <summary>
+            /// A Type 1 font program.
+            /// </summary>
             Type1,
+            /// <summary>
+            /// A TrueType font program.
+            /// </summary>
             TrueType,
+            /// <summary>
+            /// A type defined by the stream dictionary's Subtype entry.
+            /// </summary>
             FromSubtype
         }
     }

src/UglyToad.PdfPig/Fonts/FontDescriptor.cs

@@ -5,13 +5,11 @@
     using Util.JetBrains.Annotations;
 
     /// <summary>
-    /// Specifies metrics and attributes of a simple font or CID Font
+    /// Specifies metrics and attributes of a simple font or CID Font for the whole font rather than per-glyph.
-    /// for the whole font rather than per-glyph.
     /// </summary>
     /// <remarks>
     /// <para>
-    /// Provides information to enable consumer applications to
+    /// Provides information to enable consumer applications to find a substitute font when the font is unavailable.
-    /// find a substitute font when the font is unavailable.
     /// </para>
     /// <para>
     /// Font descriptors are not used with Type 0 fonts.
@@ -20,7 +18,7 @@
     /// A font descriptor is a dictionary used to specify various attributes.
     /// </para>
     /// </remarks>
-    internal class FontDescriptor
+    public class FontDescriptor
     {
         /// <summary>
         /// The PostScript name for the font.
@@ -32,13 +30,13 @@
         /// The preferred font family.
         /// </summary>
         /// <remarks>Optional</remarks>
-        public string FontFamily { get; set; }
+        public string FontFamily { get; }
 
         /// <summary>
         /// The font stretch value.
         /// </summary>
         /// <remarks>Optional</remarks>
-        public FontStretch Stretch { get; set; } = FontStretch.Normal;
+        public FontStretch Stretch { get; }
 
         /// <summary>
         /// The weight/thickness of the font.
@@ -55,20 +53,20 @@
         /// 900<br/>
         /// Optional
         /// </remarks>
-        public decimal FontWeight { get; set; } = 400;
+        public decimal FontWeight { get; }
 
         /// <summary>
-        /// Defines various font characteristics. See <see cref="FontFlags"/>.
+        /// Defines various font characteristics. See <see cref="FontDescriptorFlags"/>.
         /// </summary>
         /// <remarks>Required</remarks>
-        public FontFlags Flags { get; }
+        public FontDescriptorFlags Flags { get; }
 
         /// <summary>
         /// A rectangle in glyph coordinates which represents the smallest
         /// rectangle containing all glyphs of the font.
         /// </summary>
         /// <remarks>Required (Except Type 3)</remarks>
-        public PdfRectangle BoundingBox { get; set; }
+        public PdfRectangle BoundingBox { get; }
 
         /// <summary>
         /// The angle in degrees counter-clockwise from vertical of the vertical
@@ -77,88 +75,228 @@
         /// </summary>
         /// <example>9 o'clock is represented by 90 degrees. 3 o'clock is -90 degrees.</example>
         /// <remarks>Required</remarks>
-        public decimal ItalicAngle { get; set; }
+        public decimal ItalicAngle { get; }
 
         /// <summary>
         /// The maximum height above the baseline for any glyph from this font (except for accents).
         /// </summary>
         /// <remarks>Required (Except Type 3)</remarks>
-        public decimal Ascent { get; set; }
+        public decimal Ascent { get; }
 
         /// <summary>
         /// The maximum depth below the baseline for any glyph in the font. This is negative.
         /// </summary>
         /// <remarks>Required (Except Type 3)</remarks>
-        public decimal Descent { get; set; }
+        public decimal Descent { get; }
 
         /// <summary>
         /// The spacing between consecutive lines of text. Default 0.
         /// </summary>
         /// <remarks>Optional</remarks>
-        public decimal Leading { get; set; }
+        public decimal Leading { get; }
 
         /// <summary>
         /// The vertical distance of the top of flat capital letters from the baseline.
         /// </summary>
         /// <remarks>Required (Where Latin Characters, Except Type 3)</remarks>
-        public decimal CapHeight { get; set; }
+        public decimal CapHeight { get; }
 
         /// <summary>
         /// The x height of the font. The vertical distance of the top of flat non-ascending
         /// lowercase letters (e.g. x) from the baseline. Default 0.
         /// </summary>
         /// <remarks>Optional</remarks>
-        public decimal XHeight { get; set; }
+        public decimal XHeight { get; }
 
         /// <summary>
         /// The horizontal thickness of vertical stems of glyphs.
         /// </summary>
         /// <remarks>Required (Except Type 3)</remarks>
-        public decimal StemVertical { get; set; }
+        public decimal StemVertical { get; }
 
         /// <summary>
         /// The vertical thickness of horizontal stems of glyphs. Default 0.
         /// </summary>
         /// <remarks>Optional</remarks>
-        public decimal StemHorizontal { get; set; }
+        public decimal StemHorizontal { get; }
 
         /// <summary>
         /// The average glyph width in the font. Default 0.
         /// </summary>
         /// <remarks>Optional</remarks>
-        public decimal AverageWidth { get; set; }
+        public decimal AverageWidth { get; }
 
         /// <summary>
         /// The maximum glyph width in the font. Default 0.
         /// </summary>
         /// <remarks>Optional</remarks>
-        public decimal MaxWidth { get; set; }
+        public decimal MaxWidth { get; }
 
         /// <summary>
         /// The width for character codes whose widths are not present in the Widths
         /// array of the font dictionary. Default 0.
         /// </summary>
         /// <remarks>Optional</remarks>
-        public decimal MissingWidth { get; set; }
+        public decimal MissingWidth { get; }
 
         /// <summary>
         /// The bytes of the font program.
         /// </summary>
         /// <remarks>Optional</remarks>
         [CanBeNull]
-        public DescriptorFontFile FontFile { get; set; }
+        public DescriptorFontFile FontFile { get; }
 
         /// <summary>
         /// The character names defined in a font subset.
         /// </summary>
         /// <remarks>Optional</remarks>
         [CanBeNull]
-        public string CharSet { get; set; }
+        public string CharSet { get; }
 
-        public FontDescriptor(NameToken name, FontFlags flags)
+        /// <summary>
+        /// Create a new <see cref="FontDescriptor"/>.
+        /// </summary>
+        public FontDescriptor(Builder builder)
         {
-            FontName = name;
+            FontName = builder.FontName;
-            Flags = flags;
+            FontFamily = builder.FontFamily;
+            Stretch = builder.Stretch;
+            FontWeight = builder.FontWeight;
+            Flags = builder.Flags;
+            BoundingBox = builder.BoundingBox;
+            ItalicAngle = builder.ItalicAngle;
+            Ascent = builder.Ascent;
+            Descent = builder.Descent;
+            Leading = builder.Leading;
+            CapHeight = builder.CapHeight;
+            XHeight = builder.XHeight;
+            StemVertical = builder.StemVertical;
+            StemHorizontal = builder.StemHorizontal;
+            AverageWidth = builder.AverageWidth;
+            MaxWidth = builder.MaxWidth;
+            MissingWidth = builder.MissingWidth;
+            FontFile = builder.FontFile;
+            CharSet = builder.CharSet;
+        }
+
+        /// <summary>
+        /// Provides a mutable way to construct a <see cref="FontDescriptor"/>.
+        /// </summary>
+        public class Builder
+        {
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.FontName"/>.
+            /// </summary>
+            public NameToken FontName { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.FontFamily"/>.
+            /// </summary>
+            public string FontFamily { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.Stretch"/>.
+            /// </summary>
+            public FontStretch Stretch { get; set; } = FontStretch.Normal;
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.FontWeight"/>.
+            /// </summary>
+            public decimal FontWeight { get; set; } = 400;
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.Flags"/>.
+            /// </summary>
+            public FontDescriptorFlags Flags { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.BoundingBox"/>.
+            /// </summary>
+            public PdfRectangle BoundingBox { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.ItalicAngle"/>.
+            /// </summary>
+            public decimal ItalicAngle { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.Ascent"/>.
+            /// </summary>
+            public decimal Ascent { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.Descent"/>.
+            /// </summary>
+            public decimal Descent { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.Leading"/>.
+            /// </summary>
+            public decimal Leading { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.CapHeight"/>.
+            /// </summary>
+            public decimal CapHeight { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.XHeight"/>.
+            /// </summary>
+            public decimal XHeight { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.StemVertical"/>.
+            /// </summary>
+            public decimal StemVertical { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.StemHorizontal"/>.
+            /// </summary>
+            public decimal StemHorizontal { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.AverageWidth"/>.
+            /// </summary>
+            public decimal AverageWidth { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.MaxWidth"/>.
+            /// </summary>
+            public decimal MaxWidth { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.MissingWidth"/>.
+            /// </summary>
+            public decimal MissingWidth { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.FontFile"/>.
+            /// </summary>
+            [CanBeNull]
+            public DescriptorFontFile FontFile { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.CharSet"/>.
+            /// </summary>
+            [CanBeNull]
+            public string CharSet { get; set; }
+
+            /// <summary>
+            /// Create a new <see cref="Builder"/>.
+            /// </summary>
+            public Builder(NameToken fontName, FontDescriptorFlags flags)
+            {
+                FontName = fontName;
+                Flags = flags;
+            }
+
+            /// <summary>
+            /// Create the <see cref="FontDescriptor"/> with values from this builder.
+            /// </summary>
+            public FontDescriptor Build()
+            {
+                return new FontDescriptor(this);
+            }
         }
     }
 }

src/UglyToad.PdfPig/Fonts/FontDescriptorFlags.cs

@@ -2,9 +2,15 @@
 {
     using System;
 
+    /// <summary>
+    /// Specifies various characteristics of a font.
+    /// </summary>
     [Flags]
-    internal enum FontFlags
+    public enum FontDescriptorFlags
     {
+        /// <summary>
+        /// No flags are set.
+        /// </summary>
         None = 0,
         /// <summary>
         /// All glyphs have the same width.

src/UglyToad.PdfPig/Fonts/FontStretch.cs

@@ -3,17 +3,47 @@
     /// <summary>
     /// The font stretch.
     /// </summary>
-    internal enum FontStretch
+    public enum FontStretch
     {
+        /// <summary>
+        /// Not specified or not a recognised value.
+        /// </summary>
         Unknown = -1,
+        /// <summary>
+        /// Ultra Condensed.
+        /// </summary>
         UltraCondensed,
+        /// <summary>
+        /// Extra Condensed.
+        /// </summary>
         ExtraCondensed,
+        /// <summary>
+        /// Condensed.
+        /// </summary>
         Condensed,
+        /// <summary>
+        /// Semi Condensed.
+        /// </summary>
         SemiCondensed,
+        /// <summary>
+        /// Normal
+        /// </summary>
         Normal,
+        /// <summary>
+        /// Semi Expanded
+        /// </summary>
         SemiExpanded,
+        /// <summary>
+        /// Expanded
+        /// </summary>
         Expanded,
+        /// <summary>
+        /// Extra Expanded
+        /// </summary>
         ExtraExpanded,
+        /// <summary>
+        /// Ultra Expanded
+        /// </summary>
         UltraExpanded
     }
 }

src/UglyToad.PdfPig/Fonts/Parser/EncodingReader.cs

@@ -97,7 +97,7 @@
         {
             Encoding encoding;
             // Symbolic fonts default to standard encoding.
-            if (descriptor?.Flags.HasFlag(FontFlags.Symbolic) == true)
+            if (descriptor?.Flags.HasFlag(FontDescriptorFlags.Symbolic) == true)
             {
                 encoding = StandardEncoding.Instance;
             }

src/UglyToad.PdfPig/Fonts/Parser/Parts/FontDescriptorFactory.cs

@@ -25,7 +25,7 @@
             var charSet = GetCharSet(dictionary);
             var fontFile = GetFontFile(dictionary);
 
-            return new FontDescriptor(name, flags)
+            return new FontDescriptor.Builder(name, flags)
             {
                  FontFamily = family,
                  Stretch = stretch,
@@ -44,7 +44,7 @@
                  MissingWidth = GetDecimalOrDefault(dictionary, NameToken.MissingWidth),
                  FontFile = fontFile,
                  CharSet = charSet
-            };
+            }.Build();
         }
 
         private static decimal GetDecimalOrDefault(DictionaryToken dictionary, NameToken name)
@@ -100,7 +100,7 @@
             return stretchName.ConvertToFontStretch();
         }
 
-        private static FontFlags GetFlags(DictionaryToken dictionary, bool isLenientParsing)
+        private static FontDescriptorFlags GetFlags(DictionaryToken dictionary, bool isLenientParsing)
         {
             var flags = dictionary.GetIntOrDefault(NameToken.Flags, -1);
 
@@ -116,7 +116,7 @@
                 }
             }
 
-            return (FontFlags) flags;
+            return (FontDescriptorFlags) flags;
         }
 
         private static PdfRectangle GetBoundingBox(DictionaryToken dictionary)

src/UglyToad.PdfPig/Writer/TrueTypeWritingFont.cs

@@ -69,7 +69,7 @@
                 { NameToken.Type, NameToken.FontDescriptor },
                 { NameToken.FontName, baseFont },
                 // TODO: get flags TrueTypeEmbedder.java
-                { NameToken.Flags, new NumericToken((int)FontFlags.Symbolic) },
+                { NameToken.Flags, new NumericToken((int)FontDescriptorFlags.Symbolic) },
                 { NameToken.FontBbox, GetBoundingBox(bbox, scaling) },
                 { NameToken.ItalicAngle, new NumericToken(postscript.ItalicAngle) },
                 { NameToken.Ascent, new NumericToken(hhead.Ascender * scaling) },