Merge pull request #426 from baynezy/feature/issue-425-docs

feature/issue 425 docs

src/Html2Markdown/Html2Markdown.csproj

@@ -10,10 +10,12 @@
     <PackageTags>Markdown;Html;Convert</PackageTags>
     <SignAssembly>True</SignAssembly>
     <AssemblyOriginatorKeyFile>Html2Markdown.snk</AssemblyOriginatorKeyFile>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
 
   <ItemGroup>
     <PackageReference Include="HtmlAgilityPack" Version="1.11.61" />
+    <PackageReference Include="JetBrains.Annotations" Version="2024.2.0" />
   </ItemGroup>
 
 </Project>

src/Html2Markdown/Replacement/AnchorTagReplacer.cs

@@ -1,11 +1,17 @@
-namespace Html2Markdown.Replacement;
-/// <summary>
-/// Replaces an anchor tag with the link text and the link URL in Markdown format.
-/// </summary>
-public class AnchorTagReplacer : CustomReplacer
+namespace Html2Markdown.Replacement
 {
-    public AnchorTagReplacer()
+    /// <summary>
+    /// Replaces an anchor tag with the link text and the link URL in Markdown format.
+    /// </summary>
+    public class AnchorTagReplacer : CustomReplacer
     {
-        CustomAction = HtmlParser.ReplaceAnchor;
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AnchorTagReplacer"/> class.
+        /// Sets the custom action to replace anchor tags with Markdown formatted links.
+        /// </summary>
+        public AnchorTagReplacer()
+        {
+            CustomAction = HtmlParser.ReplaceAnchor;
+        }
     }
 }

src/Html2Markdown/Replacement/BlockquoteTagReplacer.cs

@@ -1,9 +1,14 @@
 namespace Html2Markdown.Replacement;
+
 /// <summary>
-/// Replaces an anchor tag with the link text and the link URL in Markdown format.
+/// Replaces a blockquote tag with the appropriate Markdown format.
 /// </summary>
 public class BlockquoteTagReplacer : CustomReplacer
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="BlockquoteTagReplacer"/> class.
+    /// Sets the custom action to replace blockquote tags with Markdown formatted blockquotes.
+    /// </summary>
     public BlockquoteTagReplacer()
     {
         CustomAction = HtmlParser.ReplaceBlockquote;

src/Html2Markdown/Replacement/BodyTagReplacer.cs

@@ -1,9 +1,14 @@
 namespace Html2Markdown.Replacement;
+
 /// <summary>
 /// Removes the body tag.
 /// </summary>
 public class BodyTagReplacer : PatternReplacer
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="BodyTagReplacer"/> class.
+    /// Sets the pattern to match body tags and the replacement to an empty string.
+    /// </summary>
     public BodyTagReplacer()
     {
         Pattern = "</?body[^>]*>";

src/Html2Markdown/Replacement/BreakTagReplacer.cs

@@ -1,9 +1,14 @@
 namespace Html2Markdown.Replacement;
+
 /// <summary>
 /// Replaces the HTML break tag with its Markdown equivalent.
 /// </summary>
 public class BreakTagReplacer : PatternReplacer
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="BreakTagReplacer"/> class.
+    /// Sets the pattern to match break tags and the replacement to a Markdown line break.
+    /// </summary>
     public BreakTagReplacer()
     {
         Pattern = "<br[^>]*>";

src/Html2Markdown/Replacement/CodeTagReplacer.cs

@@ -1,14 +1,24 @@
 namespace Html2Markdown.Replacement;
+
 /// <summary>
 /// Replaces the HTML code tag with its Markdown equivalent.
 /// </summary>
 public class CodeTagReplacer : CustomReplacer
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CodeTagReplacer"/> class.
+    /// Sets the custom action to replace code tags with Markdown formatted code blocks.
+    /// </summary>
     public CodeTagReplacer()
     {
         CustomAction = html => HtmlParser.ReplaceCode(html, false);
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CodeTagReplacer"/> class with an option to support syntax highlighting.
+    /// Sets the custom action to replace code tags with Markdown formatted code blocks, optionally supporting syntax highlighting.
+    /// </summary>
+    /// <param name="supportSyntaxHighlighting">If set to <c>true</c>, supports syntax highlighting in the Markdown output.</param>
     public CodeTagReplacer(bool supportSyntaxHighlighting)
     {
         CustomAction = html => HtmlParser.ReplaceCode(html, supportSyntaxHighlighting);

src/Html2Markdown/Replacement/CommonMark/CommonMarkLayoutReplacementGroup.cs

@@ -1,22 +1,26 @@
 namespace Html2Markdown.Replacement.CommonMark;
 
 /// <summary>
-/// A group of IReplacer to deal with converting HTML that is
-/// used for layout
+/// A group of <see cref="IReplacer"/> to deal with converting HTML that is
+/// used for layout.
 /// </summary>
 public class CommonMarkLayoutReplacementGroup : IReplacementGroup
 {
-	private readonly IList<IReplacer> _replacements = new List<IReplacer> {
-		new HorizontalRuleTagReplacer(),
-		new CodeTagReplacer(true),
-		new PreTagReplacer(),
-		new ParagraphTagReplacer(),
-		new BreakTagReplacer(),
-		new BlockquoteTagReplacer()
-	};
+    private readonly IList<IReplacer> _replacements = new List<IReplacer> {
+        new HorizontalRuleTagReplacer(),
+        new CodeTagReplacer(true),
+        new PreTagReplacer(),
+        new ParagraphTagReplacer(),
+        new BreakTagReplacer(),
+        new BlockquoteTagReplacer()
+    };
 
-	public IEnumerable<IReplacer> Replacers()
-	{
-		return _replacements;
-	}
+    /// <summary>
+    /// Returns the list of <see cref="IReplacer"/> instances.
+    /// </summary>
+    /// <returns>An <see cref="IEnumerable{T}"/> of <see cref="IReplacer"/>.</returns>
+    public IEnumerable<IReplacer> Replacers()
+    {
+        return _replacements;
+    }
 }

src/Html2Markdown/Replacement/CompositeReplacer.cs

@@ -1,16 +1,26 @@
 namespace Html2Markdown.Replacement;
+
 /// <summary>
 /// Allows for multiple replacements to be applied to the HTML.
 /// </summary>
 public abstract class CompositeReplacer : IReplacer
 {
     private readonly IList<IReplacer> _replacements = new List<IReplacer>();
-
+
+    /// <summary>
+    /// Adds a replacer to the list of replacements.
+    /// </summary>
+    /// <param name="replacer">The <see cref="IReplacer"/> instance to add.</param>
     protected void AddReplacer(IReplacer replacer)
     {
         _replacements.Add(replacer);
     }
-
+
+    /// <summary>
+    /// Applies all replacements to the given HTML string.
+    /// </summary>
+    /// <param name="html">The HTML string to process.</param>
+    /// <returns>The processed HTML string with all replacements applied.</returns>
     public string Replace(string html)
     {
         return _replacements.Aggregate(html, (current, replacer) => replacer.Replace(current));

src/Html2Markdown/Replacement/CustomReplacer.cs

@@ -1,13 +1,25 @@
+using JetBrains.Annotations;
+
 namespace Html2Markdown.Replacement;
+
 /// <summary>
-/// Allows custom replacement of HTML tags utilising external functions.
+/// Allows custom replacement of HTML tags utilizing external functions.
 /// </summary>
 public class CustomReplacer : IReplacer
 {
-	public string Replace(string html)
-	{
-		return CustomAction.Invoke(html);
-	}
+    /// <summary>
+    /// Replaces the HTML string using the custom action.
+    /// </summary>
+    /// <param name="html">The HTML string to process.</param>
+    /// <returns>The processed HTML string with the custom replacement applied.</returns>
+    public string Replace(string html)
+    {
+        return CustomAction.Invoke(html);
+    }
 
-	public Func<string, string> CustomAction { get; init; }
+    /// <summary>
+    /// Gets or sets the custom action to be used for replacing HTML tags.
+    /// </summary>
+    [PublicAPI]
+    public Func<string, string> CustomAction { get; init; }
 }

src/Html2Markdown/Replacement/DocTypeReplacer.cs

@@ -1,9 +1,14 @@
 namespace Html2Markdown.Replacement;
+
 /// <summary>
 /// Removes the doctype tag.
 /// </summary>
 public class DocTypeReplacer : PatternReplacer
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DocTypeReplacer"/> class.
+    /// Sets the pattern to match doctype tags and the replacement to an empty string.
+    /// </summary>
     public DocTypeReplacer()
     {
         Pattern = "<!DOCTYPE[^>]*>";

src/Html2Markdown/Replacement/EmphasisTagReplacer.cs

@@ -1,29 +1,34 @@
 namespace Html2Markdown.Replacement;
+
 /// <summary>
 /// Replaces the HTML emphasis tag with its Markdown equivalent.
 /// </summary>
 public class EmphasisTagReplacer : CompositeReplacer
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="EmphasisTagReplacer"/> class.
+    /// Sets up the patterns and replacements for converting HTML emphasis tags to Markdown.
+    /// </summary>
     public EmphasisTagReplacer()
     {
         AddReplacer(new PatternReplacer
         {
             Pattern = @"<(?:em|i)>(\s+)",
             Replacement = " *"
         });
-        
+
         AddReplacer(new PatternReplacer
         {
             Pattern = "<(?:em|i)>",
             Replacement = "*"
         });
-        
+
         AddReplacer(new PatternReplacer
         {
             Pattern = @"(\s+)</(em|i)>",
             Replacement = "* "
         });
-        
+
         AddReplacer(new PatternReplacer
         {
             Pattern = "</(em|i)>",

src/Html2Markdown/Replacement/EntitiesReplacementGroup.cs

@@ -1,16 +1,20 @@
 namespace Html2Markdown.Replacement;
 
 /// <summary>
-/// A group of IReplacer to deal with converting HTML entities
+/// A group of <see cref="IReplacer"/> to deal with converting HTML entities.
 /// </summary>
 public class EntitiesReplacementGroup : IReplacementGroup
 {
-	private readonly IList<IReplacer> _replacements = new List<IReplacer> {
-		new HtmlEntitiesReplacer()
-	};
+    private readonly IList<IReplacer> _replacements = new List<IReplacer> {
+        new HtmlEntitiesReplacer()
+    };
 
-	public IEnumerable<IReplacer> Replacers()
-	{
-		return _replacements;
-	}
+    /// <summary>
+    /// Returns the list of <see cref="IReplacer"/> instances.
+    /// </summary>
+    /// <returns>An <see cref="IEnumerable{T}"/> of <see cref="IReplacer"/>.</returns>
+    public IEnumerable<IReplacer> Replacers()
+    {
+        return _replacements;
+    }
 }

src/Html2Markdown/Replacement/HeadTagReplacer.cs

@@ -1,9 +1,14 @@
 namespace Html2Markdown.Replacement;
+
 /// <summary>
 /// Removes the doctype tag.
 /// </summary>
 public class HeadTagReplacer : PatternReplacer
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="HeadTagReplacer"/> class.
+    /// Sets up the pattern and replacement for removing HTML head tags.
+    /// </summary>
     public HeadTagReplacer()
     {
         Pattern = "</?head[^>]*>";

src/Html2Markdown/Replacement/Heading.cs

@@ -1,13 +1,37 @@
 namespace Html2Markdown.Replacement;
+
 /// <summary>
 /// HTML Heading Tag Enum
 /// </summary>
 public enum Heading
 {
+    /// <summary>
+    /// Represents an HTML H1 tag.
+    /// </summary>
     H1 = 1,
+
+    /// <summary>
+    /// Represents an HTML H2 tag.
+    /// </summary>
     H2 = 2,
+
+    /// <summary>
+    /// Represents an HTML H3 tag.
+    /// </summary>
     H3 = 3,
+
+    /// <summary>
+    /// Represents an HTML H4 tag.
+    /// </summary>
     H4 = 4,
+
+    /// <summary>
+    /// Represents an HTML H5 tag.
+    /// </summary>
     H5 = 5,
+
+    /// <summary>
+    /// Represents an HTML H6 tag.
+    /// </summary>
     H6 = 6
 }

src/Html2Markdown/Replacement/HeadingReplacementGroup.cs

@@ -1,21 +1,25 @@
 namespace Html2Markdown.Replacement;
 
 /// <summary>
-/// A group of IReplacer to deal with converting HTML headers
+/// A group of <see cref="IReplacer"/> to deal with converting HTML headers.
 /// </summary>
 public class HeadingReplacementGroup : IReplacementGroup
 {
-	private readonly IList<IReplacer> _replacements = new List<IReplacer> {
-		new HeadingTagReplacer(Heading.H1),
-		new HeadingTagReplacer(Heading.H2),
-		new HeadingTagReplacer(Heading.H3),
-		new HeadingTagReplacer(Heading.H4),
-		new HeadingTagReplacer(Heading.H5),
-		new HeadingTagReplacer(Heading.H6)
-	};
+    private readonly IList<IReplacer> _replacements = new List<IReplacer> {
+        new HeadingTagReplacer(Heading.H1),
+        new HeadingTagReplacer(Heading.H2),
+        new HeadingTagReplacer(Heading.H3),
+        new HeadingTagReplacer(Heading.H4),
+        new HeadingTagReplacer(Heading.H5),
+        new HeadingTagReplacer(Heading.H6)
+    };
 
-	public IEnumerable<IReplacer> Replacers()
-	{
-		return _replacements;
-	}
+    /// <summary>
+    /// Returns the list of <see cref="IReplacer"/> instances.
+    /// </summary>
+    /// <returns>An <see cref="IEnumerable{T}"/> of <see cref="IReplacer"/>.</returns>
+    public IEnumerable<IReplacer> Replacers()
+    {
+        return _replacements;
+    }
 }