Documentation: Dynamic Component

Source/QuestPDF/Elements/Dynamic.cs

@@ -80,6 +80,9 @@ namespace QuestPDF.Elements
         }
     }
 
+    /// <summary>
+    /// Stores all contextual information available for the dynamic component.
+    /// </summary>
     public class DynamicContext
     {
         internal IPageContext PageContext { get; set; }
@@ -92,10 +95,30 @@ namespace QuestPDF.Elements
         internal ImageCompressionQuality ImageCompressionQuality { get; set; }
         internal bool UseOriginalImage { get; set; }
         
+        /// <summary>
+        /// Returns the number of the page being rendered at the moment.
+        /// </summary>
         public int PageNumber { get; internal set; }
+        
+        /// <summary>
+        /// Returns the total count of pages in the document.
+        /// </summary>
+        /// <remarks>
+        /// Document rendering occurs in two phases.
+        /// The value of this property might be imprecise during the initial rendering phase.
+        /// </remarks>
         public int TotalPages { get; internal set; }
+        
+        /// <summary>
+        /// Returns the vertical and horizontal space, in points, available to the dynamic component.
+        /// </summary>
         public Size AvailableSize { get; internal set; }
 
+        /// <summary>
+        /// Enables the creation of unattached layout structures and provides their size measurements.
+        /// </summary>
+        /// <param name="content">The handler responsible for constructing the new layout structure.</param>
+        /// <returns>A newly created content, with its physical size.</returns>
         public IDynamicElement CreateElement(Action<IContainer> content)
         {
             var container = new DynamicElement();
@@ -114,8 +137,14 @@ namespace QuestPDF.Elements
         }
     }
 
+    /// <summary>
+    /// Represents any unattached content element, created by the dynamic component.
+    /// </summary>
     public interface IDynamicElement : IElement
     {
+        /// <summary>
+        /// Specifies the vertical and horizontal size, measured in points, required by the element to be drawn completely, assuming infinite canvas.
+        /// </summary>
         Size Size { get; }
     }
 

Source/QuestPDF/Fluent/DynamicComponentExtensions.cs

@@ -5,12 +5,27 @@ namespace QuestPDF.Fluent
 {
     public static class DynamicComponentExtensions
     {
+        /// <summary>
+        /// Represents a section of the document dynamically created based on its inner state.
+        /// Components are page-aware, understand their positioning, can dynamically construct other content elements, and assess their dimensions, enabling complex layout creations.
+        /// <a href="https://www.questpdf.com/concepts/dynamic-components.html">Learn more</a>
+        /// </summary>
+        /// <example>
+        /// <para>
+        /// Consider an invoice that presents all purchased items in a table format.
+        /// Instead of just showing the final total price under the table, the requirement is to display the cumulative prices on each separate page.
+        /// </para>
+        /// <para>Using the dynamic component, you can manually assemble the table, count how many items are visible on each page, calculate the price sum for items visible on each page, and then render the result under each sub-table.</para>
+        /// </example>
         public static void Dynamic<TState>(this IContainer element, IDynamicComponent<TState> dynamicElement) where TState : struct
         {
             var componentProxy = DynamicComponentProxy.CreateFrom(dynamicElement);
             element.Element(new DynamicHost(componentProxy));
         }
         
+        /// <summary>
+        /// Allows to inject the unattached content created by the <see cref="DynamicContext.CreateElement"/> method within the <see cref="DynamicComponentExtensions.Dynamic">Dynamic component</see>.
+        /// </summary>
         public static void Element(this IContainer element, IDynamicElement child)
         {
             ElementExtensions.Element(element, child);

Source/QuestPDF/Infrastructure/IComponent.cs

@@ -14,7 +14,6 @@ namespace QuestPDF.Infrastructure
     
     /// <summary>
     /// <para>This interface represents a reusable document fragment.</para>
-    ///
     /// <para>
     /// Components serve as modular building blocks for abstracting document layouts. 
     /// They promote code reusability across multiple sections or types of documents. 

Source/QuestPDF/Infrastructure/IDynamicComponent.cs

@@ -21,15 +21,54 @@ namespace QuestPDF.Infrastructure
         }
     }
 
+    /// <summary>
+    /// Represents the output from the DynamicComponent describing what should be rendered on the current page.
+    /// </summary>
     public class DynamicComponentComposeResult
     {
+        /// <summary>
+        /// Any content created with the <see cref="DynamicContext.CreateElement" /> method that should be drawn on the currently rendered page.
+        /// </summary>
         public IElement Content { get; set; }
+        
+        /// <summary>
+        /// Set to true if the dynamic component has additional content for the next page.
+        /// Set to false if all content from the dynamic component has been rendered.
+        /// </summary>
         public bool HasMoreContent { get; set; }
     }
     
+    /// <summary>
+    /// Represents a section of the document dynamically created based on its inner state.
+    /// Components are page-aware, understand their positioning, can dynamically construct other content elements, and assess their dimensions, enabling complex layout creations.
+    /// </summary>
+    /// <remarks>
+    /// Though dynamic components offer great flexibility, be cautious of potential performance impacts.
+    /// </remarks>
+    /// <typeparam name="TState">Structure type representing the internal state of the component.</typeparam>
     public interface IDynamicComponent<TState> where TState : struct
     {
+        /// <summary>
+        /// Represents the component's current state.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// The state should remain read-only.
+        /// Avoid direct state modifications.
+        /// For any alterations, generate a new struct instance and reassign the State property.
+        /// </para>
+        /// <para>Remember, the QuestPDF library can invoke the Compose method more than once for each page and might adjust the state internally.</para>
+        /// </remarks>
         TState State { get; set; }
+        
+        /// <summary>
+        /// Method invoked by the library to plan and create new content for each page. 
+        /// </summary>
+        /// <remarks>
+        /// Remember, the QuestPDF library can invoke the Compose method more than once for each page and might adjust the state internally.
+        /// </remarks>
+        /// <param name="context">Context offering additional information (like current page number, entire document size) and the capability to produce dynamic content elements.</param>
+        /// <returns>Representation of content that should be placed on the current page.</returns>
         DynamicComponentComposeResult Compose(DynamicContext context);
     }
 }

Source/QuestPDF/Resources/Documentation.xml

@@ -406,8 +406,5 @@
             Consider the scenario of a company-wide page header. 
             Instead of replicating the same header design across various documents, a single component can be created and referenced wherever needed.
         </example>
-        <param name="component">An instance of the class implementing the <see cref="IComponent" /> interface.</param>
-    </doc>   
-    
-    
+    </doc>
 </documentation>