chore: Add Scope method for automatic indentation management (#15)

* chore: Initial plan

* chore: Initial plan for Scope method implementation

Co-authored-by: samtrion <3283596+samtrion@users.noreply.github.com>

* chore: Implement Scope method for automatic indentation management with comprehensive tests

Co-authored-by: samtrion <3283596+samtrion@users.noreply.github.com>

* chore: Add example usage test and restore original build configuration

Co-authored-by: samtrion <3283596+samtrion@users.noreply.github.com>

* chore: Update the implementation

* chore: Exteded `AppendXmlDocSee` and `AppendXmlDocSeeAlso` with `href`

* test: Updated tests

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: samtrion <3283596+samtrion@users.noreply.github.com>
Co-authored-by: Martin Stühmer <me@samtrion.net>

Author: Copilot

src/NetEvolve.CodeBuilder/CSharpCodeBuilder.Append.cs

@@ -197,7 +197,7 @@ public CSharpCodeBuilder Append(string? value)
             return this;
         }
 
-        if (value is "\n" or "\r")
+        if (value is "\n" or "\r" or "\r\n")
         {
             return AppendLine(); // Handle new line characters
         }

src/NetEvolve.CodeBuilder/CSharpCodeBuilder.Documentation.cs

@@ -129,7 +129,8 @@ public CSharpCodeBuilder AppendXmlDocRemarks(string? remarks)
 
         return EnsureNewLineForXmlDoc()
             .AppendLine("/// <remarks>")
-            .AppendLine($"/// {remarks}")
+            .Append("/// ")
+            .AppendLine(remarks)
             .AppendLine("/// </remarks>");
     }
 
@@ -176,6 +177,17 @@ public CSharpCodeBuilder AppendXmlDocException(string? exceptionType, string? de
             .AppendLine($"/// <exception cref=\"{exceptionType}\">{description}</exception>");
     }
 
+    /// <summary>
+    /// Appends an XML documentation exception element.
+    /// </summary>
+    /// <param name="description">The description of when the exception is thrown.</param>
+    /// <typeparam name="TException">The type of exception that can be thrown. Must be a subclass of <see cref="Exception"/>.</typeparam>
+    /// <returns>The current <see cref="CSharpCodeBuilder"/> instance to allow for method chaining.</returns>
+    /// <remarks>If the exception type or description is null or empty, the method returns without appending anything.</remarks>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public CSharpCodeBuilder AppendXmlDocException<TException>(string? description)
+        where TException : Exception => AppendXmlDocException(typeof(TException).Name, description);
+
     /// <summary>
     /// Appends multiple XML documentation exception elements.
     /// </summary>
@@ -246,32 +258,34 @@ public CSharpCodeBuilder AppendXmlDocExample(IEnumerable<string>? exampleLines)
     /// Appends an XML documentation see element for cross-references.
     /// </summary>
     /// <param name="cref">The cross-reference to another member or type.</param>
+    /// <param name="isHref">If set to <c>true</c>, uses 'href' instead of 'cref' for external links.</param>
     /// <returns>The current <see cref="CSharpCodeBuilder"/> instance to allow for method chaining.</returns>
     /// <remarks>If the cref is null or empty, the method returns without appending anything.</remarks>
-    public CSharpCodeBuilder AppendXmlDocSee(string? cref)
+    public CSharpCodeBuilder AppendXmlDocSee(string? cref, bool isHref = false)
     {
         if (string.IsNullOrEmpty(cref))
         {
             return this;
         }
 
-        return EnsureNewLineForXmlDoc().AppendLine($"/// <see cref=\"{cref}\"/>");
+        return EnsureNewLineForXmlDoc().AppendLine($"/// <see {(isHref ? "href" : "cref")}=\"{cref}\"/>");
     }
 
     /// <summary>
     /// Appends an XML documentation seealso element for see-also references.
     /// </summary>
     /// <param name="cref">The cross-reference to another member or type.</param>
+    /// <param name="isHref">If set to <c>true</c>, uses 'href' instead of 'cref' for external links.</param>
     /// <returns>The current <see cref="CSharpCodeBuilder"/> instance to allow for method chaining.</returns>
     /// <remarks>If the cref is null or empty, the method returns without appending anything.</remarks>
-    public CSharpCodeBuilder AppendXmlDocSeeAlso(string? cref)
+    public CSharpCodeBuilder AppendXmlDocSeeAlso(string? cref, bool isHref = false)
     {
         if (string.IsNullOrEmpty(cref))
         {
             return this;
         }
 
-        return EnsureNewLineForXmlDoc().AppendLine($"/// <seealso cref=\"{cref}\"/>");
+        return EnsureNewLineForXmlDoc().AppendLine($"/// <seealso {(isHref ? "href" : "cref")}=\"{cref}\"/>");
     }
 
     /// <summary>

src/NetEvolve.CodeBuilder/CSharpCodeBuilder.Scope.cs

@@ -0,0 +1,91 @@
+namespace NetEvolve.CodeBuilder;
+
+using System;
+
+public partial record CSharpCodeBuilder
+{
+    /// <summary>
+    /// Creates a scope that automatically manages indentation levels.
+    /// </summary>
+    /// <returns>A <see cref="ScopeHandler"/> that increments indentation on creation and decrements on disposal.</returns>
+    /// <remarks>
+    /// The returned scope handler implements <see cref="IDisposable"/> and is designed for use with
+    /// the 'using' statement. When the scope is created, indentation is incremented by one level.
+    /// When the scope is disposed (at the end of the using block), indentation is decremented.
+    /// </remarks>
+    /// <example>
+    /// <code>
+    /// using (builder.Scope())
+    /// {
+    ///     builder.AppendLine("return true;");
+    /// }
+    /// </code>
+    /// </example>
+    public IDisposable Scope() => new ScopeHandler(this);
+
+    /// <summary>
+    /// A disposable struct that manages indentation scope for a <see cref="CSharpCodeBuilder"/>.
+    /// </summary>
+    /// <remarks>
+    /// This struct increments the indentation level when created and decrements it when disposed.
+    /// It is designed to work with the 'using' statement to provide automatic indentation management.
+    /// </remarks>
+    private readonly struct ScopeHandler : IDisposable, IEquatable<ScopeHandler>
+    {
+        private readonly CSharpCodeBuilder _builder;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ScopeHandler"/> struct and increments the indentation level.
+        /// </summary>
+        /// <param name="builder">The <see cref="CSharpCodeBuilder"/> instance to manage indentation for.</param>
+        internal ScopeHandler(CSharpCodeBuilder builder)
+        {
+            _builder = builder;
+            _ = _builder.Append('{');
+        }
+
+        /// <summary>
+        /// Decrements the indentation level when the scope is disposed.
+        /// </summary>
+        /// <remarks>
+        /// This method is called automatically when the 'using' statement block ends.
+        /// </remarks>
+        public void Dispose() => _ = _builder.Append('}');
+
+        /// <summary>
+        /// Determines whether the specified object is equal to the current instance.
+        /// </summary>
+        /// <param name="obj">The object to compare with the current instance.</param>
+        /// <returns>Always returns <c>false</c> since ScopeHandler instances should not be compared.</returns>
+        public override readonly bool Equals(object? obj) => false;
+
+        /// <summary>
+        /// Determines whether the specified ScopeHandler is equal to the current instance.
+        /// </summary>
+        /// <param name="other">The ScopeHandler to compare with the current instance.</param>
+        /// <returns>Always returns <c>false</c> since ScopeHandler instances should not be compared.</returns>
+        public readonly bool Equals(ScopeHandler other) => false;
+
+        /// <summary>
+        /// Returns the hash code for this instance.
+        /// </summary>
+        /// <returns>A hash code based on the internal builder reference.</returns>
+        public override readonly int GetHashCode() => _builder?.GetHashCode() ?? 0;
+
+        /// <summary>
+        /// Determines whether two ScopeHandler instances are equal.
+        /// </summary>
+        /// <param name="_">The first instance to compare.</param>
+        /// <param name="__">The second instance to compare.</param>
+        /// <returns>Always returns <c>false</c> since ScopeHandler instances should not be compared.</returns>
+        public static bool operator ==(ScopeHandler _, ScopeHandler __) => false;
+
+        /// <summary>
+        /// Determines whether two ScopeHandler instances are not equal.
+        /// </summary>
+        /// <param name="_">The first instance to compare.</param>
+        /// <param name="__">The second instance to compare.</param>
+        /// <returns>Always returns <c>true</c> since ScopeHandler instances should not be compared.</returns>
+        public static bool operator !=(ScopeHandler _, ScopeHandler __) => true;
+    }
+}

tests/NetEvolve.CodeBuilder.Tests.Integration/CSharpCodeBuilderTests.Formatting.cs

@@ -1,4 +1,4 @@
-namespace NetEvolve.CodeBuilder.Tests.Integration;
+namespace NetEvolve.CodeBuilder.Tests.Integration;
 
 public partial class CSharpCodeBuilderTests
 {
@@ -114,4 +114,30 @@ public async Task GenerateEnum_WithDocumentation_Should_ProduceCorrectOutput()
 
         _ = await Verify(result);
     }
+
+    [Test]
+    public async Task Scopes_in_wild_nature()
+    {
+        var builder = new CSharpCodeBuilder()
+            .AppendLine("namespace Hello.World;")
+            .AppendLine()
+            .AppendXmlDocSummary("Represents the status of an order.")
+            .AppendLine("public enum Weekday");
+
+        using (builder.Scope())
+        {
+            _ = builder
+                .AppendLine("Monday,")
+                .AppendLine("Tuesday,")
+                .AppendLine("Wednesday,")
+                .AppendLine("Thursday,")
+                .AppendLine("Friday,")
+                .AppendLine("Saturday,")
+                .AppendLine("Sunday,");
+        }
+
+        var result = builder.ToString();
+
+        _ = await Verify(result);
+    }
 }

tests/NetEvolve.CodeBuilder.Tests.Integration/_snapshots/CSharpCodeBuilderTests.Scopes_in_wild_nature.verified.txt

@@ -0,0 +1,15 @@
+namespace Hello.World;
+
+/// <summary>
+/// Represents the status of an order.
+/// </summary>
+public enum Weekday
+{
+    Monday,
+    Tuesday,
+    Wednesday,
+    Thursday,
+    Friday,
+    Saturday,
+    Sunday,
+}