Update some XML doc comments per feedback (#56886)

* IndentedTextWriter

* StringInfo

* StringSegment

* GHC

* Remove HTML

* feedback

diff --git a/src/libraries/Microsoft.Extensions.Hosting/src/HostingHostBuilderExtensions.cs b/src/libraries/Microsoft.Extensions.Hosting/src/HostingHostBuilderExtensions.cs
index 9f5e509..f0f0031 100644 (file)
--- a/src/libraries/Microsoft.Extensions.Hosting/src/HostingHostBuilderExtensions.cs
+++ b/src/libraries/Microsoft.Extensions.Hosting/src/HostingHostBuilderExtensions.cs
@@ -173,17 +173,15 @@ namespace Microsoft.Extensions.Hosting
         /// </summary>
         /// <remarks>
         ///   The following defaults are applied to the <see cref="IHostBuilder"/>:
-        ///   <list type="bullet">
-        ///     <item><description>set the <see cref="IHostEnvironment.ContentRootPath"/> to the result of <see cref="Directory.GetCurrentDirectory()"/></description></item>
-        ///     <item><description>load host <see cref="IConfiguration"/> from "DOTNET_" prefixed environment variables</description></item>
-        ///     <item><description>load host <see cref="IConfiguration"/> from supplied command line args</description></item>
-        ///     <item><description>load app <see cref="IConfiguration"/> from 'appsettings.json' and 'appsettings.[<see cref="IHostEnvironment.EnvironmentName"/>].json'</description></item>
-        ///     <item><description>load app <see cref="IConfiguration"/> from User Secrets when <see cref="IHostEnvironment.EnvironmentName"/> is 'Development' using the entry assembly</description></item>
-        ///     <item><description>load app <see cref="IConfiguration"/> from environment variables</description></item>
-        ///     <item><description>load app <see cref="IConfiguration"/> from supplied command line args</description></item>
-        ///     <item><description>configure the <see cref="ILoggerFactory"/> to log to the console, debug, and event source output</description></item>
-        ///     <item><description>enables scope validation on the dependency injection container when <see cref="IHostEnvironment.EnvironmentName"/> is 'Development'</description></item>
-        ///   </list>
+        ///     * set the <see cref="IHostEnvironment.ContentRootPath"/> to the result of <see cref="Directory.GetCurrentDirectory()"/>
+        ///     * load host <see cref="IConfiguration"/> from "DOTNET_" prefixed environment variables
+        ///     * load host <see cref="IConfiguration"/> from supplied command line args
+        ///     * load app <see cref="IConfiguration"/> from 'appsettings.json' and 'appsettings.[<see cref="IHostEnvironment.EnvironmentName"/>].json'
+        ///     * load app <see cref="IConfiguration"/> from User Secrets when <see cref="IHostEnvironment.EnvironmentName"/> is 'Development' using the entry assembly
+        ///     * load app <see cref="IConfiguration"/> from environment variables
+        ///     * load app <see cref="IConfiguration"/> from supplied command line args
+        ///     * configure the <see cref="ILoggerFactory"/> to log to the console, debug, and event source output
+        ///     * enables scope validation on the dependency injection container when <see cref="IHostEnvironment.EnvironmentName"/> is 'Development'
         /// </remarks>
         /// <param name="builder">The existing builder to configure.</param>
         /// <param name="args">The command line args.</param>

diff --git a/src/libraries/Microsoft.Extensions.Primitives/src/StringSegment.cs b/src/libraries/Microsoft.Extensions.Primitives/src/StringSegment.cs
index f1cd6ca..c5a7027 100644 (file)
--- a/src/libraries/Microsoft.Extensions.Primitives/src/StringSegment.cs
+++ b/src/libraries/Microsoft.Extensions.Primitives/src/StringSegment.cs
@@ -183,7 +183,11 @@ namespace Microsoft.Extensions.Primitives
             }
         }
 
-        /// <inheritdoc />
+        /// <summary>
+        /// Indicates whether the current object is equal to another object of the same type.
+        /// </summary>
+        /// <param name="obj">An object to compare with this object.</param>
+        /// <returns><see langword="true" /> if the current object is equal to the other parameter; otherwise, <see langword="false" />.</returns>
         public override bool Equals(object obj)
         {
             return obj is StringSegment segment && Equals(segment);
@@ -266,7 +270,12 @@ namespace Microsoft.Extensions.Primitives
             return AsSpan().Equals(text.AsSpan(), comparisonType);
         }
 
-        /// <inheritdoc />
+        /// <summary>
+        /// Returns a hash code for this instance.
+        /// </summary>
+        /// <returns>
+        /// A hash code for this instance, suitable for use in hashing algorithms and data structures like a hash table.
+        /// </returns>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public override int GetHashCode()
         {

diff --git a/src/libraries/System.Private.CoreLib/src/System/CodeDom/Compiler/IndentedTextWriter.cs b/src/libraries/System.Private.CoreLib/src/System/CodeDom/Compiler/IndentedTextWriter.cs
index a502674..58db6fa 100644 (file)
--- a/src/libraries/System.Private.CoreLib/src/System/CodeDom/Compiler/IndentedTextWriter.cs
+++ b/src/libraries/System.Private.CoreLib/src/System/CodeDom/Compiler/IndentedTextWriter.cs
@@ -193,10 +193,10 @@ namespace System.CodeDom.Compiler
         }
 
         /// <summary>
-        /// Asynchronously writes the specified value to the underlying <see cref="TextWriter"/>, inserting tabs at the
+        /// Asynchronously writes the specified string to the underlying <see cref="TextWriter"/>, inserting tabs at the
         /// start of every line.
         /// </summary>
-        /// <param name="value">The value to write.</param>
+        /// <param name="value">The string to write.</param>
         /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
         public override async Task WriteAsync(string? value)
         {
@@ -205,10 +205,10 @@ namespace System.CodeDom.Compiler
         }
 
         /// <summary>
-        /// Asynchronously writes the specified buffer to the underlying <see cref="TextWriter"/>, inserting tabs at the
+        /// Asynchronously writes the specified characters to the underlying <see cref="TextWriter"/>, inserting tabs at the
         /// start of every line.
         /// </summary>
-        /// <param name="buffer">The buffer to write.</param>
+        /// <param name="buffer">The characters to write.</param>
         /// <param name="cancellationToken">Token for canceling the operation.</param>
         /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
         public override async Task WriteAsync(ReadOnlyMemory<char> buffer, CancellationToken cancellationToken = default)
@@ -218,10 +218,10 @@ namespace System.CodeDom.Compiler
         }
 
         /// <summary>
-        /// Asynchronously writes the specified <see cref="StringBuilder"/> to the underlying <see cref="TextWriter"/>, inserting tabs at the
+        /// Asynchronously writes the contents of the specified <see cref="StringBuilder"/> to the underlying <see cref="TextWriter"/>, inserting tabs at the
         /// start of every line.
         /// </summary>
-        /// <param name="value">The value to write.</param>
+        /// <param name="value">The text to write.</param>
         /// <param name="cancellationToken">Token for canceling the operation.</param>
         /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
         public override async Task WriteAsync(StringBuilder? value, CancellationToken cancellationToken = default)
@@ -236,9 +236,9 @@ namespace System.CodeDom.Compiler
         }
 
         /// <summary>
-        /// Asynchronously writes the specified text to the underlying <see cref="TextWriter"/> without inserting tabs.
+        /// Asynchronously writes the specified string to the underlying <see cref="TextWriter"/> without inserting tabs.
         /// </summary>
-        /// <param name="s">The text to write.</param>
+        /// <param name="s">The string to write.</param>
         /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
         public Task WriteLineNoTabsAsync(string? s)
         {
@@ -363,7 +363,7 @@ namespace System.CodeDom.Compiler
         /// Asynchronously writes the specified <see cref="char"/> to the underlying <see cref="TextWriter"/> followed by a line terminator, inserting tabs
         /// at the start of every line.
         /// </summary>
-        /// <param name="value">The value to write.</param>
+        /// <param name="value">The character to write.</param>
         /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
         public override async Task WriteLineAsync(char value)
         {
@@ -376,7 +376,7 @@ namespace System.CodeDom.Compiler
         /// Asynchronously writes the specified number of characters from the specified buffer followed by a line terminator,
         /// to the underlying <see cref="TextWriter"/>, starting at the specified index within the buffer, inserting tabs at the start of every line.
         /// </summary>
-        /// <param name="buffer">The buffer to write from.</param>
+        /// <param name="buffer">The buffer containing characters to write.</param>
         /// <param name="index">The index within the buffer to start writing at.</param>
         /// <param name="count">The number of characters to write.</param>
         /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
@@ -388,10 +388,10 @@ namespace System.CodeDom.Compiler
         }
 
         /// <summary>
-        /// Asynchronously writes the specified value followed by a line terminator to the underlying <see cref="TextWriter"/>, inserting
+        /// Asynchronously writes the specified string followed by a line terminator to the underlying <see cref="TextWriter"/>, inserting
         /// tabs at the start of every line.
         /// </summary>
-        /// <param name="value">The value to write.</param>
+        /// <param name="value">The string to write.</param>
         /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
         public override async Task WriteLineAsync(string? value)
         {
@@ -401,10 +401,10 @@ namespace System.CodeDom.Compiler
         }
 
         /// <summary>
-        /// Asynchronously writes the specified buffer followed by a line terminator to the underlying <see cref="TextWriter"/>, inserting
+        /// Asynchronously writes the specified characters followed by a line terminator to the underlying <see cref="TextWriter"/>, inserting
         /// tabs at the start of every line.
         /// </summary>
-        /// <param name="buffer">The buffer to write from.</param>
+        /// <param name="buffer">The characters to write.</param>
         /// <param name="cancellationToken">Token for canceling the operation.</param>
         /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
         public override async Task WriteLineAsync(ReadOnlyMemory<char> buffer, CancellationToken cancellationToken = default)
@@ -415,8 +415,8 @@ namespace System.CodeDom.Compiler
         }
 
         /// <summary>
-        /// Asynchronously writes the specified text followed by a line terminator to the underlying <see cref="TextWriter"/>, inserting
-        /// tabs at the start of every line.
+        /// Asynchronously writes the contents of the specified <see cref="StringBuilder"/> followed by a line terminator to the
+        /// underlying <see cref="TextWriter"/>, inserting tabs at the start of every line.
         /// </summary>
         /// <param name="value">The text to write.</param>
         /// <param name="cancellationToken">Token for canceling the operation.</param>

diff --git a/src/libraries/System.Private.CoreLib/src/System/Globalization/StringInfo.cs b/src/libraries/System.Private.CoreLib/src/System/Globalization/StringInfo.cs
index fe9aee0..1e4c698 100644 (file)
--- a/src/libraries/System.Private.CoreLib/src/System/Globalization/StringInfo.cs
+++ b/src/libraries/System.Private.CoreLib/src/System/Globalization/StringInfo.cs
@@ -97,6 +97,9 @@ namespace System.Globalization
         /// <summary>
         /// Returns the first text element (extended grapheme cluster) that occurs in the input string.
         /// </summary>
+        /// <remarks>
+        /// A grapheme cluster is a sequence of one or more Unicode code points that should be treated as a single unit.
+        /// </remarks>
         /// <param name="str">The input string to analyze.</param>
         /// <returns>The substring corresponding to the first text element within <paramref name="str"/>,
         /// or the empty string if <paramref name="str"/> is empty.</returns>
@@ -107,6 +110,9 @@ namespace System.Globalization
         /// Returns the first text element (extended grapheme cluster) that occurs in the input string
         /// starting at the specified index.
         /// </summary>
+        /// <remarks>
+        /// A grapheme cluster is a sequence of one or more Unicode code points that should be treated as a single unit.
+        /// </remarks>
         /// <param name="str">The input string to analyze.</param>
         /// <param name="index">The char offset in <paramref name="str"/> at which to begin analysis.</param>
         /// <returns>The substring corresponding to the first text element within <paramref name="str"/> starting
@@ -123,6 +129,9 @@ namespace System.Globalization
         /// <summary>
         /// Returns the length of the first text element (extended grapheme cluster) that occurs in the input string.
         /// </summary>
+        /// <remarks>
+        /// A grapheme cluster is a sequence of one or more Unicode code points that should be treated as a single unit.
+        /// </remarks>
         /// <param name="str">The input string to analyze.</param>
         /// <returns>The length (in chars) of the substring corresponding to the first text element within <paramref name="str"/>,
         /// or 0 if <paramref name="str"/> is empty.</returns>
@@ -133,6 +142,9 @@ namespace System.Globalization
         /// Returns the length of the first text element (extended grapheme cluster) that occurs in the input string
         /// starting at the specified index.
         /// </summary>
+        /// <remarks>
+        /// A grapheme cluster is a sequence of one or more Unicode code points that should be treated as a single unit.
+        /// </remarks>
         /// <param name="str">The input string to analyze.</param>
         /// <param name="index">The char offset in <paramref name="str"/> at which to begin analysis.</param>
         /// <returns>The length (in chars) of the substring corresponding to the first text element within <paramref name="str"/> starting
@@ -156,6 +168,9 @@ namespace System.Globalization
         /// <summary>
         /// Returns the length of the first text element (extended grapheme cluster) that occurs in the input span.
         /// </summary>
+        /// <remarks>
+        /// A grapheme cluster is a sequence of one or more Unicode code points that should be treated as a single unit.
+        /// </remarks>
         /// <param name="str">The input span to analyze.</param>
         /// <returns>The length (in chars) of the substring corresponding to the first text element within <paramref name="str"/>,
         /// or 0 if <paramref name="str"/> is empty.</returns>