Skip to content

Commit 9ec5d76

Browse files
authored
Improve documentation comments (#221)
1 parent a768225 commit 9ec5d76

File tree

5 files changed

+71
-75
lines changed

5 files changed

+71
-75
lines changed

src/LinkDotNet.StringBuilder/ValueStringBuilder.Append.cs

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ namespace LinkDotNet.StringBuilder;
77
public ref partial struct ValueStringBuilder
88
{
99
/// <summary>
10-
/// Appends the string representation of the boolean to the builder.
10+
/// Appends the string representation of the boolean.
1111
/// </summary>
1212
/// <param name="value">Bool value to add.</param>
1313
[MethodImpl(MethodImplOptions.AggressiveInlining)]
@@ -46,7 +46,7 @@ public unsafe void Append(bool value)
4646
}
4747

4848
/// <summary>
49-
/// Appends the string representation of the character to the builder.
49+
/// Appends the string representation of the value.
5050
/// </summary>
5151
/// <param name="value">Formattable span to add.</param>
5252
/// <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
5858
where T : ISpanFormattable => AppendSpanFormattable(value, format, bufferSize);
5959

6060
/// <summary>
61-
/// Appends a string to the string builder.
61+
/// Appends a string.
6262
/// </summary>
63-
/// <param name="str">String, which will be added to this builder.</param>
63+
/// <param name="str">String to be added to this builder.</param>
6464
[MethodImpl(MethodImplOptions.AggressiveInlining)]
6565
public void Append(scoped ReadOnlySpan<char> str)
6666
{
@@ -81,7 +81,7 @@ ref Unsafe.As<char, byte>(ref strRef),
8181
}
8282

8383
/// <summary>
84-
/// Appends a character buffer to this builder.
84+
/// Appends a character buffer.
8585
/// </summary>
8686
/// <param name="value">The pointer to the start of the buffer.</param>
8787
/// <param name="length">The number of characters in the buffer.</param>
@@ -102,7 +102,7 @@ public void Append(ReadOnlyMemory<char> memory)
102102
}
103103

104104
/// <summary>
105-
/// Appends a single character to the string builder.
105+
/// Appends a single character.
106106
/// </summary>
107107
/// <param name="value">Character to add.</param>
108108
[MethodImpl(MethodImplOptions.AggressiveInlining)]
@@ -142,7 +142,7 @@ public void AppendLine()
142142
}
143143

144144
/// <summary>
145-
/// Does the same as <see cref="Append(char)"/> but adds a newline at the end.
145+
/// Calls <see cref="Append(ReadOnlySpan{char})"/> and appends a newline.
146146
/// </summary>
147147
/// <param name="str">String to be added to this builder.</param>
148148
[MethodImpl(MethodImplOptions.AggressiveInlining)]
@@ -153,9 +153,9 @@ public void AppendLine(scoped ReadOnlySpan<char> str)
153153
}
154154

155155
/// <summary>
156-
/// Increases the size of the string builder returning a span of the length appended.
156+
/// Appends a span of the given length, which can be written to later.
157157
/// </summary>
158-
/// <param name="length">Integer representing the length to be appended.</param>
158+
/// <param name="length">Integer representing the number of characters to be appended.</param>
159159
/// <returns>A span with the characters appended.</returns>
160160
[MethodImpl(MethodImplOptions.AggressiveInlining)]
161161
public Span<char> AppendSpan(int length)

src/LinkDotNet.StringBuilder/ValueStringBuilder.AppendFormat.cs

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -65,8 +65,8 @@ public void AppendFormat<T>(
6565
/// <param name="format">Format string.</param>
6666
/// <param name="arg1">Argument for <c>{0}</c>.</param>
6767
/// <param name="arg2">Argument for <c>{1}</c>.</param>
68-
/// <typeparam name="T1">Any type for <param name="arg1"></param>.</typeparam>
69-
/// <typeparam name="T2">Any type for <param name="arg2"></param>.</typeparam>
68+
/// <typeparam name="T1">Any type for <paramref name="arg1"/>.</typeparam>
69+
/// <typeparam name="T2">Any type for <paramref name="arg2"/>.</typeparam>
7070
/// <remarks>
7171
/// The current version does not allow for a custom format.
7272
/// So: <code>AppendFormat("{0:00}")</code> is not allowed and will result in an exception.
@@ -132,9 +132,9 @@ public void AppendFormat<T1, T2>(
132132
/// <param name="arg1">Argument for <c>{0}</c>.</param>
133133
/// <param name="arg2">Argument for <c>{1}</c>.</param>
134134
/// <param name="arg3">Argument for <c>{2}</c>.</param>
135-
/// <typeparam name="T1">Any type for <param name="arg1"></param>.</typeparam>
136-
/// <typeparam name="T2">Any type for <param name="arg2"></param>.</typeparam>
137-
/// <typeparam name="T3">Any type for <param name="arg3"></param>.</typeparam>
135+
/// <typeparam name="T1">Any type for <paramref name="arg1"/>.</typeparam>
136+
/// <typeparam name="T2">Any type for <paramref name="arg2"/>.</typeparam>
137+
/// <typeparam name="T3">Any type for <paramref name="arg3"/>.</typeparam>
138138
/// <remarks>
139139
/// The current version does not allow for a custom format.
140140
/// 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>(
205205
/// <param name="arg2">Argument for <c>{1}</c>.</param>
206206
/// <param name="arg3">Argument for <c>{2}</c>.</param>
207207
/// <param name="arg4">Argument for <c>{3}</c>.</param>
208-
/// <typeparam name="T1">Any type for <param name="arg1"></param>.</typeparam>
209-
/// <typeparam name="T2">Any type for <param name="arg2"></param>.</typeparam>
210-
/// <typeparam name="T3">Any type for <param name="arg3"></param>.</typeparam>
211-
/// <typeparam name="T4">Any type for <param name="arg4"></param>.</typeparam>
208+
/// <typeparam name="T1">Any type for <paramref name="arg1"/>.</typeparam>
209+
/// <typeparam name="T2">Any type for <paramref name="arg2"/>.</typeparam>
210+
/// <typeparam name="T3">Any type for <paramref name="arg3"/>.</typeparam>
211+
/// <typeparam name="T4">Any type for <paramref name="arg4"/>.</typeparam>
212212
/// <remarks>
213213
/// The current version does not allow for a custom format.
214214
/// 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>(
284284
/// <param name="arg3">Argument for <c>{2}</c>.</param>
285285
/// <param name="arg4">Argument for <c>{3}</c>.</param>
286286
/// <param name="arg5">Argument for <c>{4}</c>.</param>
287-
/// <typeparam name="T1">Any type for <param name="arg1"></param>.</typeparam>
288-
/// <typeparam name="T2">Any type for <param name="arg2"></param>.</typeparam>
289-
/// <typeparam name="T3">Any type for <param name="arg3"></param>.</typeparam>
290-
/// <typeparam name="T4">Any type for <param name="arg4"></param>.</typeparam>
291-
/// <typeparam name="T5">Any type for <param name="arg5"></param>.</typeparam>
287+
/// <typeparam name="T1">Any type for <paramref name="arg1"/>.</typeparam>
288+
/// <typeparam name="T2">Any type for <paramref name="arg2"/>.</typeparam>
289+
/// <typeparam name="T3">Any type for <paramref name="arg3"/>.</typeparam>
290+
/// <typeparam name="T4">Any type for <paramref name="arg4"/>.</typeparam>
291+
/// <typeparam name="T5">Any type for <paramref name="arg5"/>.</typeparam>
292292
/// <remarks>
293293
/// The current version does not allow for a custom format.
294294
/// So: <code>AppendFormat("{0:00}")</code> is not allowed and will result in an exception.

src/LinkDotNet.StringBuilder/ValueStringBuilder.Enumerator.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ public readonly char Current
3232
}
3333

3434
/// <summary>Advances the enumerator to the next element of the span.</summary>
35-
/// <returns>True if the enumerator was successfully advancing to the next element; false if the enumerator has passed the end of the span.</returns>
35+
/// <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>
3636
[MethodImpl(MethodImplOptions.AggressiveInlining)]
3737
public bool MoveNext() => ++index < span.Length;
3838
}

src/LinkDotNet.StringBuilder/ValueStringBuilder.Replace.cs

Lines changed: 45 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -47,56 +47,12 @@ public readonly void Replace(char oldValue, char newValue, int startIndex, int c
4747
/// <param name="oldValue">The string to replace.</param>
4848
/// <param name="newValue">The string to replace <paramref name="oldValue"/> with.</param>
4949
/// <remarks>
50-
/// If <paramref name="newValue"/> is <c>empty</c>, instances of <paramref name="oldValue"/>
51-
/// are removed from this builder.
50+
/// If <paramref name="newValue"/> is <c>empty</c>, instances of <paramref name="oldValue"/> are removed.
5251
/// </remarks>
5352
[MethodImpl(MethodImplOptions.AggressiveInlining)]
5453
public void Replace(ReadOnlySpan<char> oldValue, ReadOnlySpan<char> newValue)
5554
=> Replace(oldValue, newValue, 0, Length);
5655

57-
/// <summary>
58-
/// Replaces all instances of one string with another in this builder.
59-
/// </summary>
60-
/// <param name="oldValue">The string to replace.</param>
61-
/// <param name="newValue">Object to replace <paramref name="oldValue"/> with.</param>
62-
/// <remarks>
63-
/// If <paramref name="newValue"/> is from type <see cref="ISpanFormattable"/> an optimized version is taken.
64-
/// Otherwise the ToString method is called.
65-
/// </remarks>
66-
/// /// <typeparam name="T">Any type.</typeparam>
67-
[MethodImpl(MethodImplOptions.AggressiveInlining)]
68-
public void ReplaceGeneric<T>(ReadOnlySpan<char> oldValue, T newValue)
69-
=> ReplaceGeneric(oldValue, newValue, 0, Length);
70-
71-
/// <summary>
72-
/// Replaces all instances of one string with another in this builder.
73-
/// </summary>
74-
/// <param name="oldValue">The string to replace.</param>
75-
/// <param name="newValue">Object to replace <paramref name="oldValue"/> with.</param>
76-
/// <param name="startIndex">The index to start in this builder.</param>
77-
/// <param name="count">The number of characters to read in this builder.</param>
78-
/// <remarks>
79-
/// If <paramref name="newValue"/> is from type <see cref="ISpanFormattable"/> an optimized version is taken.
80-
/// Otherwise the ToString method is called.
81-
/// </remarks>
82-
/// /// <typeparam name="T">Any type.</typeparam>
83-
[MethodImpl(MethodImplOptions.AggressiveInlining)]
84-
public void ReplaceGeneric<T>(ReadOnlySpan<char> oldValue, T newValue, int startIndex, int count)
85-
{
86-
if (newValue is ISpanFormattable spanFormattable)
87-
{
88-
Span<char> tempBuffer = stackalloc char[24];
89-
if (spanFormattable.TryFormat(tempBuffer, out var written, default, null))
90-
{
91-
Replace(oldValue, tempBuffer[..written], startIndex, count);
92-
}
93-
}
94-
else
95-
{
96-
Replace(oldValue, (ReadOnlySpan<char>)newValue?.ToString(), startIndex, count);
97-
}
98-
}
99-
10056
/// <summary>
10157
/// Replaces all instances of one string with another in this builder.
10258
/// </summary>
@@ -105,8 +61,7 @@ public void ReplaceGeneric<T>(ReadOnlySpan<char> oldValue, T newValue, int start
10561
/// <param name="startIndex">The index to start in this builder.</param>
10662
/// <param name="count">The number of characters to read in this builder.</param>
10763
/// <remarks>
108-
/// If <paramref name="newValue"/> is <c>empty</c>, instances of <paramref name="oldValue"/>
109-
/// are removed from this builder.
64+
/// If <paramref name="newValue"/> is <c>empty</c>, instances of <paramref name="oldValue"/> are removed.
11065
/// </remarks>
11166
[MethodImpl(MethodImplOptions.AggressiveInlining)]
11267
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
160115
}
161116
}
162117
}
118+
119+
/// <summary>
120+
/// Replaces all instances of one string with another in this builder.
121+
/// </summary>
122+
/// <param name="oldValue">The string to replace.</param>
123+
/// <param name="newValue">Object to replace <paramref name="oldValue"/> with.</param>
124+
/// <remarks>
125+
/// If <paramref name="newValue"/> is from type <see cref="ISpanFormattable"/> an optimized version is taken.
126+
/// Otherwise the ToString method is called.
127+
/// </remarks>
128+
/// /// <typeparam name="T">Any type.</typeparam>
129+
[MethodImpl(MethodImplOptions.AggressiveInlining)]
130+
public void ReplaceGeneric<T>(ReadOnlySpan<char> oldValue, T newValue)
131+
=> ReplaceGeneric(oldValue, newValue, 0, Length);
132+
133+
/// <summary>
134+
/// Replaces all instances of one string with another in this builder.
135+
/// </summary>
136+
/// <param name="oldValue">The string to replace.</param>
137+
/// <param name="newValue">Object to replace <paramref name="oldValue"/> with.</param>
138+
/// <param name="startIndex">The index to start in this builder.</param>
139+
/// <param name="count">The number of characters to read in this builder.</param>
140+
/// <remarks>
141+
/// If <paramref name="newValue"/> is from type <see cref="ISpanFormattable"/> an optimized version is taken.
142+
/// Otherwise the ToString method is called.
143+
/// </remarks>
144+
/// /// <typeparam name="T">Any type.</typeparam>
145+
[MethodImpl(MethodImplOptions.AggressiveInlining)]
146+
public void ReplaceGeneric<T>(ReadOnlySpan<char> oldValue, T newValue, int startIndex, int count)
147+
{
148+
if (newValue is ISpanFormattable spanFormattable)
149+
{
150+
Span<char> tempBuffer = stackalloc char[24];
151+
if (spanFormattable.TryFormat(tempBuffer, out var written, default, null))
152+
{
153+
Replace(oldValue, tempBuffer[..written], startIndex, count);
154+
}
155+
}
156+
else
157+
{
158+
Replace(oldValue, (ReadOnlySpan<char>)newValue?.ToString(), startIndex, count);
159+
}
160+
}
163161
}

src/LinkDotNet.StringBuilder/ValueStringBuilder.cs

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -49,9 +49,7 @@ public ValueStringBuilder(Span<char> initialBuffer)
4949
/// <summary>
5050
/// Initializes a new instance of the <see cref="ValueStringBuilder"/> struct.
5151
/// </summary>
52-
/// <param name="initialText">The initial text used to initialize this instance. If <paramref name="initialText"/> is <c>null</c>
53-
/// the <see cref="ValueStringBuilder"/> will return an empty string (<see cref="string.Empty"/>).
54-
/// </param>
52+
/// <param name="initialText">The initial text used to initialize this instance.</param>
5553
[MethodImpl(MethodImplOptions.AggressiveInlining)]
5654
public ValueStringBuilder(ReadOnlySpan<char> initialText)
5755
{
@@ -291,7 +289,7 @@ public readonly int LastIndexOf(ReadOnlySpan<char> word, int startIndex)
291289
/// Returns a value indicating whether the characters in this instance are equal to the characters in a specified read-only character span.
292290
/// </summary>
293291
/// <param name="span">The character span to compare with the current instance.</param>
294-
/// <returns><c>true</c> if the characters are equal to this instance, otherwise <c>false</c>.</returns>
292+
/// <returns><see langword="true"/> if the characters are equal to this instance, otherwise <see langword="false"/>.</returns>
295293
[MethodImpl(MethodImplOptions.AggressiveInlining)]
296294
public readonly bool Equals(ReadOnlySpan<char> span) => span.SequenceEqual(AsSpan());
297295

0 commit comments

Comments
 (0)