More XML comments

Author: synercoder

src/Synercoding.FileFormats.Pdf/Extensions/IPageContentContextExtensions.cs

@@ -8,8 +8,21 @@
 using System.Threading.Tasks;
 
 namespace Synercoding.FileFormats.Pdf.Extensions;
+
+/// <summary>
+/// Extension methods for <see cref="IPageContentContext"/>
+/// </summary>
 public static class IPageContentContextExtensions
 {
+    /// <summary>
+    /// Add a JPG stream directly to the page
+    /// </summary>
+    /// <param name="context">The context to add the image to.</param>
+    /// <param name="jpgStream">The stream containing a JPG image</param>
+    /// <param name="originalWidth">The width of the JPG in the <paramref name="jpgStream"/>.</param>
+    /// <param name="originalHeight">The height of the JPG in the <paramref name="jpgStream"/>.</param>
+    /// <param name="colorSpace">The colorspace of the JPG in the <paramref name="jpgStream"/>.</param>
+    /// <returns>The same <paramref name="context"/> to enable chaining operations.</returns>
     public static IPageContentContext AddJpgUnsafe(this IPageContentContext context, System.IO.Stream jpgStream, int originalWidth, int originalHeight, ColorSpace colorSpace)
     {
         var name = context.RawContentStream.Resources.AddJpgUnsafe(jpgStream, originalWidth, originalHeight, colorSpace);
@@ -19,6 +32,13 @@ public static IPageContentContext AddJpgUnsafe(this IPageContentContext context,
         return context;
     }
 
+    /// <summary>
+    /// Add an image to the page
+    /// </summary>
+    /// <param name="context">The context to add the image to.</param>
+    /// <param name="stream">The stream containing the image</param>
+    /// <param name="matrix">The placement matrix to use</param>
+    /// <returns>The same <paramref name="context"/> to enable chaining operations.</returns>
     public static IPageContentContext AddImage(this IPageContentContext context, System.IO.Stream stream, Matrix matrix)
     {
         return context.WrapInState((stream, matrix), static (tuple, context) =>
@@ -28,16 +48,36 @@ public static IPageContentContext AddImage(this IPageContentContext context, Sys
         });
     }
 
+    /// <summary>
+    /// Add an image to the page
+    /// </summary>
+    /// <param name="context">The context to add the image to.</param>
+    /// <param name="stream">The stream containing the image</param>
+    /// <param name="rectangle">The rectangle of where to place the image.</param>
+    /// <returns>The same <paramref name="context"/> to enable chaining operations.</returns>
     public static IPageContentContext AddImage(this IPageContentContext context, System.IO.Stream stream, Rectangle rectangle)
         => context.AddImage(stream, rectangle.AsPlacementMatrix());
 
+    /// <summary>
+    /// Add an image to the page
+    /// </summary>
+    /// <param name="context">The context to add the image to.</param>
+    /// <param name="stream">The stream containing the image</param>
+    /// <returns>The same <paramref name="context"/> to enable chaining operations.</returns>
     public static IPageContentContext AddImage(this IPageContentContext context, System.IO.Stream stream)
     {
         using var image = SixLabors.ImageSharp.Image.Load(stream);
 
         return context.AddImage(image);
     }
 
+    /// <summary>
+    /// Add an image to the page
+    /// </summary>
+    /// <param name="context">The context to add the image to.</param>
+    /// <param name="image">The image to place</param>
+    /// <param name="matrix">The placement matrix to use</param>
+    /// <returns>The same <paramref name="context"/> to enable chaining operations.</returns>
     public static IPageContentContext AddImage(this IPageContentContext context, SixLabors.ImageSharp.Image image, Matrix matrix)
     {
         return context.WrapInState((image, matrix), static (tuple, context) =>
@@ -47,9 +87,22 @@ public static IPageContentContext AddImage(this IPageContentContext context, Six
         });
     }
 
+    /// <summary>
+    /// Add an image to the page
+    /// </summary>
+    /// <param name="context">The context to add the image to.</param>
+    /// <param name="image">The image to place</param>
+    /// <param name="rectangle">The rectangle of where to place the image.</param>
+    /// <returns>The same <paramref name="context"/> to enable chaining operations.</returns>
     public static IPageContentContext AddImage(this IPageContentContext context, SixLabors.ImageSharp.Image image, Rectangle rectangle)
         => context.AddImage(image, rectangle.AsPlacementMatrix());
 
+    /// <summary>
+    /// Add an image to the page
+    /// </summary>
+    /// <param name="context">The context to add the image to.</param>
+    /// <param name="image">The image to place</param>
+    /// <returns>The same <paramref name="context"/> to enable chaining operations.</returns>
     public static IPageContentContext AddImage(this IPageContentContext context, SixLabors.ImageSharp.Image image)
     {
         var name = context.RawContentStream.Resources.AddImage(image);
@@ -59,9 +112,23 @@ public static IPageContentContext AddImage(this IPageContentContext context, Six
         return context;
     }
 
+    /// <summary>
+    /// Add an image to the page
+    /// </summary>
+    /// <param name="context">The context to add the image to.</param>
+    /// <param name="image">The image to place</param>
+    /// <param name="rectangle">The rectangle of where to place the image.</param>
+    /// <returns>The same <paramref name="context"/> to enable chaining operations.</returns>
     public static IPageContentContext AddImage(this IPageContentContext context, Image image, Rectangle rectangle)
         => context.AddImage(image, rectangle.AsPlacementMatrix());
 
+    /// <summary>
+    /// Add an image to the page
+    /// </summary>
+    /// <param name="context">The context to add the image to.</param>
+    /// <param name="image">The image to place</param>
+    /// <param name="matrix">The placement matrix to use</param>
+    /// <returns>The same <paramref name="context"/> to enable chaining operations.</returns>
     public static IPageContentContext AddImage(this IPageContentContext context, Image image, Matrix matrix)
     {
         return context.WrapInState((image, matrix), static (tuple, context) =>
@@ -71,27 +138,88 @@ public static IPageContentContext AddImage(this IPageContentContext context, Ima
         });
     }
 
+    /// <summary>
+    /// Start a shape operation on the page
+    /// </summary>
+    /// <param name="context">The context to add the shape to.</param>
+    /// <param name="shapeOperations">The shape operations to execute</param>
+    /// <returns>The same <paramref name="context"/> to enable chaining operations.</returns>
     public static IPageContentContext AddShapes(this IPageContentContext context, Action<IShapeContentContext> shapeOperations)
         => context.AddShapes(shapeOperations, static (operations, context) => operations(context));
 
+    /// <summary>
+    /// Start a shape operation on the page
+    /// </summary>
+    /// <param name="context">The context to add the shape to.</param>
+    /// <param name="shapeOperations">The shape operations to execute</param>
+    /// <returns>A task that resolves to <paramref name="context"/> to enable chaining operations</returns>
     public static Task<IPageContentContext> AddShapesAsync(this IPageContentContext context, Func<IShapeContentContext, Task> shapeOperations)
         => context.AddShapesAsync(shapeOperations, static (operations, context) => operations(context));
 
+    /// <summary>
+    /// Start a text operation on the page
+    /// </summary>
+    /// <param name="context">The context to add the text to.</param>
+    /// <param name="textOperations">The text operations to execute</param>
+    /// <returns>The same <paramref name="context"/> to enable chaining operations.</returns>
     public static IPageContentContext AddText(this IPageContentContext context, Action<ITextContentContext> textOperations)
         => context.AddText(textOperations, static (operations, context) => operations(context));
 
+    /// <summary>
+    /// Start a text operation on the page
+    /// </summary>
+    /// <param name="context">The context to add the text to.</param>
+    /// <param name="textOperations">The text operations to execute</param>
+    /// <returns>A task that resolves to <paramref name="context"/> to enable chaining operations</returns>
     public static Task<IPageContentContext> AddTextAsync(this IPageContentContext context, Func<ITextContentContext, Task> textOperations)
         => context.AddTextAsync(textOperations, static (operations, context) => operations(context));
 
+    /// <summary>
+    /// Show text on the page using the parameters provided
+    /// </summary>
+    /// <param name="context">The context to add the text to.</param>
+    /// <param name="text">The text to show</param>
+    /// <param name="font">The font to use</param>
+    /// <param name="size">The font size to use</param>
+    /// <returns>The same <paramref name="context"/> to enable chaining operations.</returns>
     public static IPageContentContext AddText(this IPageContentContext context, string text, Font font, double size)
         => context.AddText(text, font, size, ops => { });
 
+    /// <summary>
+    /// Show text on the page using the parameters provided
+    /// </summary>
+    /// <param name="context">The context to add the text to.</param>
+    /// <param name="text">The text to show</param>
+    /// <param name="font">The font to use</param>
+    /// <param name="size">The font size to use</param>
+    /// <param name="location">The location to place the text</param>
+    /// <returns>The same <paramref name="context"/> to enable chaining operations.</returns>
     public static IPageContentContext AddText(this IPageContentContext context, string text, Font font, double size, Point location)
         => context.AddText(text, font, size, location, static (location, ops) => ops.MoveToStartNextLine(location.X.AsRaw(Unit.Points), location.Y.AsRaw(Unit.Points)));
 
+    /// <summary>
+    /// Show text on the page using the parameters provided
+    /// </summary>
+    /// <param name="context">The context to add the text to.</param>
+    /// <param name="text">The text to show</param>
+    /// <param name="font">The font to use</param>
+    /// <param name="size">The font size to use</param>
+    /// <param name="extraOperations">The extra text operations to execute</param>
+    /// <returns>The same <paramref name="context"/> to enable chaining operations.</returns>
     public static IPageContentContext AddText(this IPageContentContext context, string text, Font font, double size, Action<ITextContentContext> extraOperations)
         => context.AddText(text, font, size, extraOperations, static (extraOperations, context) => extraOperations(context));
 
+    /// <summary>
+    /// Show text on the page using the parameters provided
+    /// </summary>
+    /// <typeparam name="T">The type of the data to provide to the <paramref name="extraOperations"/></typeparam>
+    /// <param name="context">The context to add the text to.</param>
+    /// <param name="text">The text to show</param>
+    /// <param name="font">The font to use</param>
+    /// <param name="size">The font size to use</param>
+    /// <param name="data">the data to provide to <paramref name="extraOperations"/></param>
+    /// <param name="extraOperations">The extra text operations to execute</param>
+    /// <returns>The same <paramref name="context"/> to enable chaining operations.</returns>
     public static IPageContentContext AddText<T>(this IPageContentContext context, string text, Font font, double size, T data, Action<T, ITextContentContext> extraOperations)
     {
         return context.AddText((text, font, size, data, extraOperations), static (quintuple, context) =>

src/Synercoding.FileFormats.Pdf/Extensions/IShapeContextExtensions.cs

@@ -2,8 +2,18 @@
 using Synercoding.Primitives.Extensions;
 
 namespace Synercoding.FileFormats.Pdf.Extensions;
+
+/// <summary>
+/// Extensions for <see cref="IShapeContentContext"/>
+/// </summary>
 public static class IShapeContextExtensions
 {
+    /// <summary>
+    /// Add a rectangle to the current path
+    /// </summary>
+    /// <param name="context">The context to execute this path on.</param>
+    /// <param name="rectangle">The <see cref="Synercoding.Primitives.Rectangle"/> to add.</param>
+    /// <returns>The same <paramref name="context"/> to enable chaining operations.</returns>
     public static IShapeContentContext Rectangle(this IShapeContentContext context, Rectangle rectangle)
         => context.Rectangle(rectangle.LLX.AsRaw(Unit.Points), rectangle.LLY.AsRaw(Unit.Points), rectangle.Width.AsRaw(Unit.Points), rectangle.Height.AsRaw(Unit.Points));
 }

src/Synercoding.FileFormats.Pdf/GraphicState.cs

@@ -5,13 +5,16 @@
 
 namespace Synercoding.FileFormats.Pdf;
 
+/// <summary>
+/// Class representing the grahpic state of a PDF at a certain moment in time.
+/// </summary>
 public sealed class GraphicState
 {
     internal GraphicState()
     {
         CTM = Matrix.Identity;
-        FillColor = PredefinedColors.Black;
-        StrokeColor = PredefinedColors.Black;
+        Fill = PredefinedColors.Black;
+        Stroke = PredefinedColors.Black;
         LineWidth = 1.0;
         LineCap = LineCapStyle.ButtCap;
         LineJoin = LineJoinStyle.MiterJoin;
@@ -27,30 +30,95 @@ internal GraphicState()
         TextRise = 0.0;
     }
 
-    public Matrix CTM { get; internal set; } 
-    public Color FillColor { get; internal set; } 
-    public Color StrokeColor { get; internal set; } 
-    public double LineWidth { get; internal set; } 
-    public LineCapStyle LineCap { get; internal set; } 
+    /// <summary>
+    /// The current transformation matrix, which maps positions from user coordinates to device coordinates.
+    /// This matrix is modified by each application of the coordinate transformation operator, cm
+    /// </summary>
+    public Matrix CTM { get; internal set; }
+
+    /// <summary>
+    /// The color used for filling operations
+    /// </summary>
+    public Color Fill { get; internal set; }
+
+    /// <summary>
+    /// The color used for stroking operations
+    /// </summary>
+    public Color Stroke { get; internal set; }
+
+    /// <summary>
+    /// The thickness, in user space units, of paths to be stroked.
+    /// </summary>
+    public double LineWidth { get; internal set; }
+
+    /// <summary>
+    /// A code specifying the shape of the endpoints for any open path that is stroked.
+    /// </summary>
+    public LineCapStyle LineCap { get; internal set; }
+
+    /// <summary>
+    /// A code specifying the shape of joints between connected segments of a stroked path.
+    /// </summary>
     public LineJoinStyle LineJoin { get; internal set; }
+
+    /// <summary>
+    /// The maximum length of mitered line joins for stroked paths.
+    /// This parameter limits the length of “spikes” produced when line segments join at sharp angles.
+    /// </summary>
     public double MiterLimit { get; internal set; }
-    public Dash DashPattern { get; internal set; } 
-    public double CharacterSpacing { get; internal set; } 
-    public double WordSpacing { get; internal set; } 
+
+    /// <summary>
+    /// A description of the dash pattern to be used when paths are stroked.
+    /// </summary>
+    public Dash DashPattern { get; internal set; }
+
+    /// <summary>
+    /// The spacing between characters
+    /// </summary>
+    public double CharacterSpacing { get; internal set; }
+
+    /// <summary>
+    /// The spacing between words
+    /// </summary>
+    public double WordSpacing { get; internal set; }
+
+    /// <summary>
+    /// The horizontal scaling is a number specifying the percentage of the normal width.
+    /// </summary>
     public double HorizontalScaling { get; internal set; }
+
+    /// <summary>
+    /// The text leading is a number expressed in unscaled text space units.
+    /// </summary>
     public double TextLeading { get; internal set; }
+
+    /// <summary>
+    /// The font used when placing text on the page
+    /// </summary>
     public Font? Font { get; internal set; }
+
+    /// <summary>
+    /// The font size used when placing text on the page
+    /// </summary>
     public double? FontSize { get; internal set; }
+
+    /// <summary>
+    /// The text rendering mode, determines whether showing text causes glyph outlines to be stroked, filled, used as a clipping boundary, or some combination of the three.
+    /// </summary>
     public TextRenderingMode TextRenderingMode { get; internal set; }
+
+    /// <summary>
+    /// Text rise, specifies the distance, in unscaled text space units, to move the baseline up or down from its default location.
+    /// </summary>
     public double TextRise { get; internal set; }
 
     internal GraphicState Clone()
     {
         return new GraphicState()
         {
             CTM = CTM,
-            FillColor = FillColor,
-            StrokeColor = StrokeColor,
+            Fill = Fill,
+            Stroke = Stroke,
             LineWidth = LineWidth,
             LineCap = LineCap,
             LineJoin = LineJoin,