Improve documentation comments

src/LinkDotNet.StringBuilder/ValueStringBuilder.Append.cs

@@ -7,7 +7,7 @@ namespace LinkDotNet.StringBuilder;
 public ref partial struct ValueStringBuilder
 {
     /// <summary>
-    /// Appends the string representation of the boolean to the builder.
+    /// Appends the string representation of the boolean.
     /// </summary>
     /// <param name="value">Bool value to add.</param>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
@@ -46,7 +46,7 @@ public unsafe void Append(bool value)
     }
 
     /// <summary>
-    /// Appends the string representation of the character to the builder.
+    /// Appends the string representation of the value.
     /// </summary>
     /// <param name="value">Formattable span to add.</param>
     /// <param name="format">Optional formatter. If not provided the default of the given instance is taken.</param>
@@ -58,9 +58,9 @@ public void Append<T>(T value, ReadOnlySpan<char> format = default, int bufferSi
         where T : ISpanFormattable => AppendSpanFormattable(value, format, bufferSize);
 
     /// <summary>
-    /// Appends a string to the string builder.
+    /// Appends a string.
     /// </summary>
-    /// <param name="str">String, which will be added to this builder.</param>
+    /// <param name="str">String to be added to this builder.</param>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public void Append(scoped ReadOnlySpan<char> str)
     {
@@ -81,7 +81,7 @@ ref Unsafe.As<char, byte>(ref strRef),
     }
 
     /// <summary>
-    /// Appends a character buffer to this builder.
+    /// Appends a character buffer.
     /// </summary>
     /// <param name="value">The pointer to the start of the buffer.</param>
     /// <param name="length">The number of characters in the buffer.</param>
@@ -102,7 +102,7 @@ public void Append(ReadOnlyMemory<char> memory)
     }
 
     /// <summary>
-    /// Appends a single character to the string builder.
+    /// Appends a single character.
     /// </summary>
     /// <param name="value">Character to add.</param>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
@@ -142,7 +142,7 @@ public void AppendLine()
     }
 
     /// <summary>
-    /// Does the same as <see cref="Append(char)"/> but adds a newline at the end.
+    /// Calls <see cref="Append(ReadOnlySpan{char})"/> and appends a newline.
     /// </summary>
     /// <param name="str">String to be added to this builder.</param>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
@@ -153,9 +153,9 @@ public void AppendLine(scoped ReadOnlySpan<char> str)
     }
 
     /// <summary>
-    /// Increases the size of the string builder returning a span of the length appended.
+    /// Appends a span of the given length, which can be written to later.
     /// </summary>
-    /// <param name="length">Integer representing the length to be appended.</param>
+    /// <param name="length">Integer representing the number of characters to be appended.</param>
     /// <returns>A span with the characters appended.</returns>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public Span<char> AppendSpan(int length)

src/LinkDotNet.StringBuilder/ValueStringBuilder.AppendFormat.cs

@@ -65,8 +65,8 @@ public void AppendFormat<T>(
     /// <param name="format">Format string.</param>
     /// <param name="arg1">Argument for <c>{0}</c>.</param>
     /// <param name="arg2">Argument for <c>{1}</c>.</param>
-    /// <typeparam name="T1">Any type for <param name="arg1"></param>.</typeparam>
-    /// <typeparam name="T2">Any type for <param name="arg2"></param>.</typeparam>
+    /// <typeparam name="T1">Any type for <paramref name="arg1"/>.</typeparam>
+    /// <typeparam name="T2">Any type for <paramref name="arg2"/>.</typeparam>
     /// <remarks>
     /// The current version does not allow for a custom format.
     /// So: <code>AppendFormat("{0:00}")</code> is not allowed and will result in an exception.
@@ -132,9 +132,9 @@ public void AppendFormat<T1, T2>(
     /// <param name="arg1">Argument for <c>{0}</c>.</param>
     /// <param name="arg2">Argument for <c>{1}</c>.</param>
     /// <param name="arg3">Argument for <c>{2}</c>.</param>
-    /// <typeparam name="T1">Any type for <param name="arg1"></param>.</typeparam>
-    /// <typeparam name="T2">Any type for <param name="arg2"></param>.</typeparam>
-    /// <typeparam name="T3">Any type for <param name="arg3"></param>.</typeparam>
+    /// <typeparam name="T1">Any type for <paramref name="arg1"/>.</typeparam>
+    /// <typeparam name="T2">Any type for <paramref name="arg2"/>.</typeparam>
+    /// <typeparam name="T3">Any type for <paramref name="arg3"/>.</typeparam>
     /// <remarks>
     /// The current version does not allow for a custom format.
     /// So: <code>AppendFormat("{0:00}")</code> is not allowed and will result in an exception.
@@ -205,10 +205,10 @@ public void AppendFormat<T1, T2, T3>(
     /// <param name="arg2">Argument for <c>{1}</c>.</param>
     /// <param name="arg3">Argument for <c>{2}</c>.</param>
     /// <param name="arg4">Argument for <c>{3}</c>.</param>
-    /// <typeparam name="T1">Any type for <param name="arg1"></param>.</typeparam>
-    /// <typeparam name="T2">Any type for <param name="arg2"></param>.</typeparam>
-    /// <typeparam name="T3">Any type for <param name="arg3"></param>.</typeparam>
-    /// <typeparam name="T4">Any type for <param name="arg4"></param>.</typeparam>
+    /// <typeparam name="T1">Any type for <paramref name="arg1"/>.</typeparam>
+    /// <typeparam name="T2">Any type for <paramref name="arg2"/>.</typeparam>
+    /// <typeparam name="T3">Any type for <paramref name="arg3"/>.</typeparam>
+    /// <typeparam name="T4">Any type for <paramref name="arg4"/>.</typeparam>
     /// <remarks>
     /// The current version does not allow for a custom format.
     /// So: <code>AppendFormat("{0:00}")</code> is not allowed and will result in an exception.
@@ -284,11 +284,11 @@ public void AppendFormat<T1, T2, T3, T4>(
     /// <param name="arg3">Argument for <c>{2}</c>.</param>
     /// <param name="arg4">Argument for <c>{3}</c>.</param>
     /// <param name="arg5">Argument for <c>{4}</c>.</param>
-    /// <typeparam name="T1">Any type for <param name="arg1"></param>.</typeparam>
-    /// <typeparam name="T2">Any type for <param name="arg2"></param>.</typeparam>
-    /// <typeparam name="T3">Any type for <param name="arg3"></param>.</typeparam>
-    /// <typeparam name="T4">Any type for <param name="arg4"></param>.</typeparam>
-    /// <typeparam name="T5">Any type for <param name="arg5"></param>.</typeparam>
+    /// <typeparam name="T1">Any type for <paramref name="arg1"/>.</typeparam>
+    /// <typeparam name="T2">Any type for <paramref name="arg2"/>.</typeparam>
+    /// <typeparam name="T3">Any type for <paramref name="arg3"/>.</typeparam>
+    /// <typeparam name="T4">Any type for <paramref name="arg4"/>.</typeparam>
+    /// <typeparam name="T5">Any type for <paramref name="arg5"/>.</typeparam>
     /// <remarks>
     /// The current version does not allow for a custom format.
     /// So: <code>AppendFormat("{0:00}")</code> is not allowed and will result in an exception.

src/LinkDotNet.StringBuilder/ValueStringBuilder.Enumerator.cs

@@ -32,7 +32,7 @@ public readonly char Current
         }
 
         /// <summary>Advances the enumerator to the next element of the span.</summary>
-        /// <returns>True if the enumerator was successfully advancing to the next element; false if the enumerator has passed the end of the span.</returns>
+        /// <returns><see langword="true"/> if the enumerator successfully advanced to the next element; <see langword="false"/> if the enumerator reached the end of the span.</returns>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public bool MoveNext() => ++index < span.Length;
     }

src/LinkDotNet.StringBuilder/ValueStringBuilder.Replace.cs

@@ -47,56 +47,12 @@ public readonly void Replace(char oldValue, char newValue, int startIndex, int c
     /// <param name="oldValue">The string to replace.</param>
     /// <param name="newValue">The string to replace <paramref name="oldValue"/> with.</param>
     /// <remarks>
-    /// If <paramref name="newValue"/> is <c>empty</c>, instances of <paramref name="oldValue"/>
-    /// are removed from this builder.
+    /// If <paramref name="newValue"/> is <c>empty</c>, instances of <paramref name="oldValue"/> are removed.
     /// </remarks>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public void Replace(ReadOnlySpan<char> oldValue, ReadOnlySpan<char> newValue)
         => Replace(oldValue, newValue, 0, Length);
 
-    /// <summary>
-    /// Replaces all instances of one string with another in this builder.
-    /// </summary>
-    /// <param name="oldValue">The string to replace.</param>
-    /// <param name="newValue">Object to replace <paramref name="oldValue"/> with.</param>
-    /// <remarks>
-    /// If <paramref name="newValue"/> is from type <see cref="ISpanFormattable"/> an optimized version is taken.
-    /// Otherwise the ToString method is called.
-    /// </remarks>
-    /// /// <typeparam name="T">Any type.</typeparam>
-    [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public void ReplaceGeneric<T>(ReadOnlySpan<char> oldValue, T newValue)
-        => ReplaceGeneric(oldValue, newValue, 0, Length);
-
-    /// <summary>
-    /// Replaces all instances of one string with another in this builder.
-    /// </summary>
-    /// <param name="oldValue">The string to replace.</param>
-    /// <param name="newValue">Object to replace <paramref name="oldValue"/> with.</param>
-    /// <param name="startIndex">The index to start in this builder.</param>
-    /// <param name="count">The number of characters to read in this builder.</param>
-    /// <remarks>
-    /// If <paramref name="newValue"/> is from type <see cref="ISpanFormattable"/> an optimized version is taken.
-    /// Otherwise the ToString method is called.
-    /// </remarks>
-    /// /// <typeparam name="T">Any type.</typeparam>
-    [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public void ReplaceGeneric<T>(ReadOnlySpan<char> oldValue, T newValue, int startIndex, int count)
-    {
-        if (newValue is ISpanFormattable spanFormattable)
-        {
-            Span<char> tempBuffer = stackalloc char[24];
-            if (spanFormattable.TryFormat(tempBuffer, out var written, default, null))
-            {
-                Replace(oldValue, tempBuffer[..written], startIndex, count);
-            }
-        }
-        else
-        {
-            Replace(oldValue, (ReadOnlySpan<char>)newValue?.ToString(), startIndex, count);
-        }
-    }
-
     /// <summary>
     /// Replaces all instances of one string with another in this builder.
     /// </summary>
@@ -105,8 +61,7 @@ public void ReplaceGeneric<T>(ReadOnlySpan<char> oldValue, T newValue, int start
     /// <param name="startIndex">The index to start in this builder.</param>
     /// <param name="count">The number of characters to read in this builder.</param>
     /// <remarks>
-    /// If <paramref name="newValue"/> is <c>empty</c>, instances of <paramref name="oldValue"/>
-    /// are removed from this builder.
+    /// If <paramref name="newValue"/> is <c>empty</c>, instances of <paramref name="oldValue"/> are removed.
     /// </remarks>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public void Replace(scoped ReadOnlySpan<char> oldValue, scoped ReadOnlySpan<char> newValue, int startIndex, int count)
@@ -160,4 +115,47 @@ public void Replace(scoped ReadOnlySpan<char> oldValue, scoped ReadOnlySpan<char
             }
         }
     }
+
+    /// <summary>
+    /// Replaces all instances of one string with another in this builder.
+    /// </summary>
+    /// <param name="oldValue">The string to replace.</param>
+    /// <param name="newValue">Object to replace <paramref name="oldValue"/> with.</param>
+    /// <remarks>
+    /// If <paramref name="newValue"/> is from type <see cref="ISpanFormattable"/> an optimized version is taken.
+    /// Otherwise the ToString method is called.
+    /// </remarks>
+    /// /// <typeparam name="T">Any type.</typeparam>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void ReplaceGeneric<T>(ReadOnlySpan<char> oldValue, T newValue)
+        => ReplaceGeneric(oldValue, newValue, 0, Length);
+
+    /// <summary>
+    /// Replaces all instances of one string with another in this builder.
+    /// </summary>
+    /// <param name="oldValue">The string to replace.</param>
+    /// <param name="newValue">Object to replace <paramref name="oldValue"/> with.</param>
+    /// <param name="startIndex">The index to start in this builder.</param>
+    /// <param name="count">The number of characters to read in this builder.</param>
+    /// <remarks>
+    /// If <paramref name="newValue"/> is from type <see cref="ISpanFormattable"/> an optimized version is taken.
+    /// Otherwise the ToString method is called.
+    /// </remarks>
+    /// /// <typeparam name="T">Any type.</typeparam>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void ReplaceGeneric<T>(ReadOnlySpan<char> oldValue, T newValue, int startIndex, int count)
+    {
+        if (newValue is ISpanFormattable spanFormattable)
+        {
+            Span<char> tempBuffer = stackalloc char[24];
+            if (spanFormattable.TryFormat(tempBuffer, out var written, default, null))
+            {
+                Replace(oldValue, tempBuffer[..written], startIndex, count);
+            }
+        }
+        else
+        {
+            Replace(oldValue, (ReadOnlySpan<char>)newValue?.ToString(), startIndex, count);
+        }
+    }
 }

src/LinkDotNet.StringBuilder/ValueStringBuilder.cs

@@ -49,9 +49,7 @@ public ValueStringBuilder(Span<char> initialBuffer)
     /// <summary>
     /// Initializes a new instance of the <see cref="ValueStringBuilder"/> struct.
     /// </summary>
-    /// <param name="initialText">The initial text used to initialize this instance. If <paramref name="initialText"/> is <c>null</c>
-    /// the <see cref="ValueStringBuilder"/> will return an empty string (<see cref="string.Empty"/>).
-    /// </param>
+    /// <param name="initialText">The initial text used to initialize this instance.</param>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public ValueStringBuilder(ReadOnlySpan<char> initialText)
     {
@@ -291,7 +289,7 @@ public readonly int LastIndexOf(ReadOnlySpan<char> word, int startIndex)
     /// Returns a value indicating whether the characters in this instance are equal to the characters in a specified read-only character span.
     /// </summary>
     /// <param name="span">The character span to compare with the current instance.</param>
-    /// <returns><c>true</c> if the characters are equal to this instance, otherwise <c>false</c>.</returns>
+    /// <returns><see langword="true"/> if the characters are equal to this instance, otherwise <see langword="false"/>.</returns>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public readonly bool Equals(ReadOnlySpan<char> span) => span.SequenceEqual(AsSpan());