fixed markdown special characters not escaped (fixes #117)

fixed unhandled xml elements not rendering as is in markdown (fixes #126)
Doraku · Oct 12, 2024 · 2ff3a44 · 2ff3a44
1 parent 3ec6ac2
commit 2ff3a44
Show file tree

Hide file tree

Showing 67 changed files with 294 additions and 168 deletions.
diff --git a/documentation/NEXT_RELEASENOTES.txt b/documentation/NEXT_RELEASENOTES.txt
@@ -12,4 +12,6 @@
 - fixed string and char const field definition
 - fixed ExplicitInterfaceImplementationsSection config name (fixes #141)
 - fixed StackOverflowException when using cyclic inheritdoc (fixes #142)
-- fixed property getter/setter access modifier not taken into account (fixes #151)
+- fixed property getter/setter access modifier not taken into account (fixes #151)
+- fixed markdown special characters not escaped (fixes #117)
+- fixed unhandled xml elements not rendering as is in markdown (fixes #126)
diff --git a/source/DefaultDocumentation.Markdown/Elements/BrElement.cs b/source/DefaultDocumentation.Markdown/Elements/BrElement.cs
@@ -0,0 +1,31 @@
+using System;
+using System.Xml.Linq;
+using DefaultDocumentation.Api;
+
+namespace DefaultDocumentation.Markdown.Elements;
+
+/// <summary>
+/// Handles <c>br</c> xml element.
+/// </summary>
+public sealed class BrElement : IElement
+{
+    /// <summary>
+    /// The name of this implementation used at the configuration level.
+    /// </summary>
+    public const string ConfigName = "br";
+
+    /// <inheritdoc/>
+    public string Name => ConfigName;
+
+    /// <inheritdoc/>
+    public void Write(IWriter writer, XElement element)
+    {
+        writer.ThrowIfNull();
+        element.ThrowIfNull();
+
+        using (writer.AppendAsRaw())
+        {
+            writer.Append("<br/>");
+        }
+    }
+}
diff --git a/source/DefaultDocumentation.Markdown/Elements/CElement.cs b/source/DefaultDocumentation.Markdown/Elements/CElement.cs
@@ -23,9 +23,12 @@ public void Write(IWriter writer, XElement element)
         writer.ThrowIfNull();
         element.ThrowIfNull();
 
-        writer
-            .Append("`")
-            .Append(element.Value)
-            .Append("`");
+        using (writer.AppendAsRaw())
+        {
+            writer
+                .Append("`")
+                .Append(element.Value)
+                .Append("`");
+        }
     }
 }
diff --git a/source/DefaultDocumentation.Markdown/Elements/CodeElement.cs b/source/DefaultDocumentation.Markdown/Elements/CodeElement.cs
@@ -2,7 +2,6 @@
 using System.IO;
 using System.Xml.Linq;
 using DefaultDocumentation.Api;
-using DefaultDocumentation.Markdown.Extensions;
 using DefaultDocumentation.Markdown.Internal;
 
 namespace DefaultDocumentation.Markdown.Elements;
@@ -59,13 +58,16 @@ public void Write(IWriter writer, XElement element)
 
         string? source = element.GetSourceAttribute();
 
-        writer
-            .EnsureLineStartAndAppendLine()
-            .Append("```")
-            .AppendLine(element.GetLanguageAttribute() ?? "csharp")
-            .Append(source is null ? element : new XElement("code", GetCode(writer.Context.Settings, source, element.GetRegionAttribute())))
-            .TrimEnd(Environment.NewLine, " ")
-            .AppendLine()
-            .Append("```");
+        using (writer.AppendAsRaw())
+        {
+            writer
+                .EnsureLineStartAndAppendLine()
+                .Append("```")
+                .AppendLine(element.GetLanguageAttribute() ?? "csharp")
+                .Append(source is null ? element : new XElement("code", GetCode(writer.Context.Settings, source, element.GetRegionAttribute())))
+                .TrimEnd(Environment.NewLine, " ")
+                .AppendLine()
+                .Append("```");
+        }
     }
 }
diff --git a/source/DefaultDocumentation.Markdown/Elements/ListElement.cs b/source/DefaultDocumentation.Markdown/Elements/ListElement.cs
@@ -2,7 +2,6 @@
 using System.Globalization;
 using System.Xml.Linq;
 using DefaultDocumentation.Api;
-using DefaultDocumentation.Markdown.Extensions;
 
 namespace DefaultDocumentation.Markdown.Elements;
 
@@ -127,19 +126,22 @@ public void Write(IWriter writer, XElement element)
             return;
         }
 
-        switch (element.GetTypeAttribute())
+        using (writer.AppendAsRaw())
         {
-            case "bullet":
-                WriteBullet(writer, element);
-                break;
+            switch (element.GetTypeAttribute())
+            {
+                case "bullet":
+                    WriteBullet(writer, element);
+                    break;
 
-            case "number":
-                WriteNumber(writer, element);
-                break;
+                case "number":
+                    WriteNumber(writer, element);
+                    break;
 
-            case "table":
-                WriteTable(writer, element);
-                break;
+                case "table":
+                    WriteTable(writer, element);
+                    break;
+            }
         }
     }
 }
diff --git a/source/DefaultDocumentation.Markdown/Elements/NoteElement.cs b/source/DefaultDocumentation.Markdown/Elements/NoteElement.cs
@@ -2,7 +2,6 @@
 using System.Globalization;
 using System.Xml.Linq;
 using DefaultDocumentation.Api;
-using DefaultDocumentation.Markdown.Extensions;
 
 namespace DefaultDocumentation.Markdown.Elements;
 
@@ -50,17 +49,20 @@ public void Write(IWriter writer, XElement element)
             _ => string.Empty
         };
 
-        writer.EnsureLineStart();
-
-        IWriter prefixedWriter = writer.ToPrefixedWriter("> ");
-        if (!string.IsNullOrEmpty(notePrefix))
+        using (writer.AppendAsRaw())
         {
-            prefixedWriter
-                .Append("**")
-                .Append(notePrefix)
-                .AppendLine(":**  ");
-        }
+            writer.EnsureLineStart();
 
-        prefixedWriter.AppendAsMarkdown(element);
+            IWriter prefixedWriter = writer.ToPrefixedWriter("> ");
+            if (!string.IsNullOrEmpty(notePrefix))
+            {
+                prefixedWriter
+                    .Append("**")
+                    .Append(notePrefix.SanitizeForMarkdown())
+                    .AppendLine(":**  ");
+            }
+
+            prefixedWriter.AppendAsMarkdown(element);
+        }
     }
 }
diff --git a/source/DefaultDocumentation.Markdown/Elements/ParaElement.cs b/source/DefaultDocumentation.Markdown/Elements/ParaElement.cs
@@ -1,6 +1,5 @@
 using System.Xml.Linq;
 using DefaultDocumentation.Api;
-using DefaultDocumentation.Markdown.Extensions;
 
 namespace DefaultDocumentation.Markdown.Elements;
 
@@ -20,8 +19,11 @@ public sealed class ParaElement : IElement
     /// <inheritdoc/>
     public void Write(IWriter writer, XElement element)
     {
-        writer
-            .EnsureLineStartAndAppendLine()
-            .AppendAsMarkdown(element);
+        using (writer.AppendAsRaw())
+        {
+            writer
+                .EnsureLineStartAndAppendLine()
+                .AppendAsMarkdown(element);
+        }
     }
 }
diff --git a/source/DefaultDocumentation.Markdown/Elements/ParamRefElement.cs b/source/DefaultDocumentation.Markdown/Elements/ParamRefElement.cs
@@ -1,7 +1,6 @@
 using System;
 using System.Xml.Linq;
 using DefaultDocumentation.Api;
-using DefaultDocumentation.Markdown.Extensions;
 using DefaultDocumentation.Models;
 using DefaultDocumentation.Models.Parameters;
 

diff --git a/source/DefaultDocumentation.Markdown/Elements/SeeElement.cs b/source/DefaultDocumentation.Markdown/Elements/SeeElement.cs
@@ -1,7 +1,6 @@
 using System;
 using System.Xml.Linq;
 using DefaultDocumentation.Api;
-using DefaultDocumentation.Markdown.Extensions;
 
 namespace DefaultDocumentation.Markdown.Elements;
 

diff --git a/source/DefaultDocumentation.Markdown/Elements/TypeParamRefElement.cs b/source/DefaultDocumentation.Markdown/Elements/TypeParamRefElement.cs
@@ -1,7 +1,6 @@
 using System;
 using System.Xml.Linq;
 using DefaultDocumentation.Api;
-using DefaultDocumentation.Markdown.Extensions;
 using DefaultDocumentation.Models;
 using DefaultDocumentation.Models.Parameters;
 

diff --git a/source/DefaultDocumentation.Markdown/Extensions/IWriterExtensions.cs b/source/DefaultDocumentation.Markdown/Extensions/IWriterExtensions.cs
@@ -1,6 +1,6 @@
 using System;
 using System.Xml.Linq;
-using DefaultDocumentation.Api;
+using DefaultDocumentation.Markdown.Internal;
 using DefaultDocumentation.Markdown.Writers;
 using DefaultDocumentation.Models;
 using DefaultDocumentation.Models.Parameters;
@@ -10,7 +10,7 @@
 using ICSharpCode.Decompiler.TypeSystem;
 using ICSharpCode.Decompiler.TypeSystem.Implementation;
 
-namespace DefaultDocumentation.Markdown.Extensions;
+namespace DefaultDocumentation.Api;
 
 /// <summary>
 /// Provides extension methods on the <see cref="IWriter"/> type.
@@ -27,6 +27,7 @@ public static class IWriterExtensions
     private const string _currentItemKey = "Markdown.CurrentItem";
     private const string _displayAsSingleLineKey = "Markdown.DisplayAsSingleLine";
     private const string _handleLineBreakKey = "Markdown.HandleLineBreak";
+    private const string _renderAsRaw = "Markdown.RenderAsRaw";
 
     /// <summary>
     /// Gets the current item that is being processed by this <see cref="IWriter"/>.
@@ -119,6 +120,51 @@ public static IWriter SetHandleLineBreak(this IWriter writer, bool? value)
         return writer;
     }
 
+    /// <summary>
+    /// Gets whether the writer should append the next strings as is without sanitizing it.
+    /// This setting is used by the <see cref="MarkdownWriter"/> type.
+    /// </summary>
+    /// <param name="writer">The <see cref="IWriter"/> for which to get this setting.</param>
+    /// <returns>Whether strings should be sanitized.</returns>
+    public static bool GetRenderAsRaw(this IWriter writer)
+    {
+        writer.ThrowIfNull();
+
+        return writer.Context[_renderAsRaw] as bool? ?? false;
+    }
+
+    /// <summary>
+    /// Sets whether the writer should append the next strings as is without sanitizing it.
+    /// This setting is used by the <see cref="MarkdownWriter"/> type.
+    /// </summary>
+    /// <param name="writer">The <see cref="IWriter"/> for which to set this setting.</param>
+    /// <param name="value">Whether strings should be sanitized.</param>
+    /// <returns>The given <see cref="IWriter"/>.</returns>
+    public static IWriter SetRenderAsRaw(this IWriter writer, bool? value)
+    {
+        writer.ThrowIfNull();
+
+        writer.Context[_renderAsRaw] = value;
+
+        return writer;
+    }
+
+    /// <summary>
+    /// Append a string without sanitizing it for markdown regardless of the current <see cref="GetRenderAsRaw(IWriter)"/> value.
+    /// </summary>
+    /// <param name="writer">The <see cref="IWriter"/> to use.</param>
+    /// <returns>The given <see cref="IWriter"/>.</returns>
+    public static IDisposable AppendAsRaw(this IWriter writer)
+    {
+        writer.ThrowIfNull();
+
+        bool? previousRenderAsRaw = writer.GetRenderAsRaw();
+
+        writer.SetRenderAsRaw(true);
+
+        return new DisposableAction(() => writer.SetRenderAsRaw(previousRenderAsRaw));
+    }
+
     /// <summary>
     /// Append an url in the markdown format.
     /// </summary>
@@ -131,20 +177,23 @@ public static IWriter AppendUrl(this IWriter writer, string? url, string? displa
     {
         writer.ThrowIfNull();
 
-        if (string.IsNullOrEmpty(url))
+        using (writer.AppendAsRaw())
         {
-            writer.Append((displayedName ?? "").Prettify());
-        }
-        else
-        {
-            writer
-                .Append("[")
-                .Append((displayedName ?? url!).Prettify())
-                .Append("](")
-                .Append(url!)
-                .Append(" '")
-                .Append(tooltip ?? url!)
-                .Append("')");
+            if (string.IsNullOrEmpty(url))
+            {
+                writer.Append((displayedName ?? "").Prettify().SanitizeForMarkdown());
+            }
+            else
+            {
+                writer
+                    .Append("[")
+                    .Append((displayedName ?? url!).Prettify().SanitizeForMarkdown())
+                    .Append("](")
+                    .Append(url!)
+                    .Append(" '")
+                    .Append((tooltip ?? url!).SanitizeForMarkdown())
+                    .Append("')");
+            }
         }
 
         return writer;

diff --git a/source/DefaultDocumentation.Markdown/Internal/DisposableAction.cs b/source/DefaultDocumentation.Markdown/Internal/DisposableAction.cs
@@ -0,0 +1,20 @@
+using System;
+
+namespace DefaultDocumentation.Markdown.Internal;
+
+internal sealed class DisposableAction : IDisposable
+{
+    private readonly Action _action;
+
+    public DisposableAction(Action action)
+    {
+        _action = action;
+    }
+
+    public void Dispose()
+    {
+        GC.SuppressFinalize(this);
+
+        _action();
+    }
+}
diff --git a/source/DefaultDocumentation.Markdown/Internal/Extensions/StringExtensions.cs b/source/DefaultDocumentation.Markdown/Internal/Extensions/StringExtensions.cs
@@ -1,7 +1,13 @@
-namespace System;
+using System.Text.RegularExpressions;
+
+namespace System;
 
 internal static class StringExtensions
 {
+    private static readonly Regex _markdownSanitization = new(@"[\\\`\*_\{\}\[\]\<\>\(\)\#\+\-\.\!\|]", RegexOptions.Compiled);
+
+    public static string SanitizeForMarkdown(this string value) => _markdownSanitization.Replace(value, @"\$&");
+
     public static string Prettify(this string value)
     {
         int genericIndex = value.IndexOf('`');

diff --git a/source/DefaultDocumentation.Markdown/Sections/ChildrenSection.cs b/source/DefaultDocumentation.Markdown/Sections/ChildrenSection.cs
@@ -3,7 +3,6 @@
 using System.Linq;
 using System.Xml.Linq;
 using DefaultDocumentation.Api;
-using DefaultDocumentation.Markdown.Extensions;
 using DefaultDocumentation.Models;
 using DefaultDocumentation.Models.Members;
 using DefaultDocumentation.Models.Parameters;

diff --git a/source/DefaultDocumentation.Markdown/Sections/DefinitionSection.cs b/source/DefaultDocumentation.Markdown/Sections/DefinitionSection.cs
@@ -1,7 +1,6 @@
 using System;
 using System.Linq;
 using DefaultDocumentation.Api;
-using DefaultDocumentation.Markdown.Extensions;
 using DefaultDocumentation.Models;
 using DefaultDocumentation.Models.Members;
 using DefaultDocumentation.Models.Parameters;

diff --git a/source/DefaultDocumentation.Markdown/Sections/DerivedSection.cs b/source/DefaultDocumentation.Markdown/Sections/DerivedSection.cs
@@ -2,7 +2,6 @@
 using System.Collections.Generic;
 using System.Linq;
 using DefaultDocumentation.Api;
-using DefaultDocumentation.Markdown.Extensions;
 using DefaultDocumentation.Models.Types;
 
 namespace DefaultDocumentation.Markdown.Sections;

diff --git a/source/DefaultDocumentation.Markdown/Sections/EventTypeSection.cs b/source/DefaultDocumentation.Markdown/Sections/EventTypeSection.cs
@@ -1,5 +1,4 @@
 using DefaultDocumentation.Api;
-using DefaultDocumentation.Markdown.Extensions;
 using DefaultDocumentation.Models.Members;
 
 namespace DefaultDocumentation.Markdown.Sections;