Apply feedback from review

ericstj · ericstj · commit 7716929291ef · 2025-10-02T11:54:41.000-07:00
diff --git a/xml/System.ComponentModel.DataAnnotations/ValidationContext.xml b/xml/System.ComponentModel.DataAnnotations/ValidationContext.xml
@@ -315,7 +315,7 @@
           <para>If <see langword="null" />, an empty dictionary will be created.  If not <see langword="null" />, the set of key/value pairs will be copied into a new dictionary, preventing consumers from modifying the original dictionary.</para>
         </param>
         <summary>
-          <para>Construct a <see cref="T:System.ComponentModel.DataAnnotations.ValidationContext" /> for a given object instance with a <paramref name="displayName" />, an optional <paramref name="serviceProvider" />, and an optional property bag of <paramref name="items" />.</para>
+          <para>Constructs a <see cref="T:System.ComponentModel.DataAnnotations.ValidationContext" /> for a given object instance with a <paramref name="displayName" />, an optional <paramref name="serviceProvider" />, and an optional property bag of <paramref name="items" />.</para>
         </summary>
         <remarks>
           <para>This constructor is trim-safe because it does not use reflection to resolve the Type of the <paramref name="instance" /> to support setting the DisplayName.</para>
diff --git a/xml/System.Data.SqlTypes/SqlDecimal.xml b/xml/System.Data.SqlTypes/SqlDecimal.xml
@@ -4371,8 +4371,8 @@ This member is an explicit interface member implementation. It can be used only
         <summary>Writes the four 32-bit unsigned integer values that make up the <see cref="T:System.Data.SqlTypes.SqlDecimal" /> structure into the <paramref name="destination" /> span.</summary>
         <returns>The number of items written to the <see cref="T:System.Span`1" />.</returns>
         <remarks>To be added.</remarks>
-        <exception cref="T:System.Data.SqlTypes.SqlNullValueException">Thrown when the <see cref="T:System.Data.SqlTypes.SqlDecimal" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.ArgumentOutOfRangeException">Thrown when the destination span is too small.</exception>
+        <exception cref="T:System.Data.SqlTypes.SqlNullValueException">The <see cref="T:System.Data.SqlTypes.SqlDecimal" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.ArgumentOutOfRangeException">The destination span is too small.</exception>
       </Docs>
     </Member>
   </Members>
diff --git a/xml/System.Data.SqlTypes/SqlMoney.xml b/xml/System.Data.SqlTypes/SqlMoney.xml
@@ -825,7 +825,7 @@
         <summary>Returns the Tabular Data Stream (TDS) long value that makes up the structure of the <see cref="T:System.Data.SqlTypes.SqlMoney" /> instance.</summary>
         <returns>A <see cref="T:System.Int64" /> that represents the TDS long value.</returns>
         <remarks>To be added.</remarks>
-        <exception cref="T:System.Data.SqlTypes.SqlNullValueException">Thrown when the <see cref="T:System.Data.SqlTypes.SqlMoney" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Data.SqlTypes.SqlNullValueException">The <see cref="T:System.Data.SqlTypes.SqlMoney" /> is <see langword="null" />.</exception>
       </Docs>
     </Member>
     <Member MemberName="GetXsdType">
diff --git a/xml/System.Data/DataRowView.xml b/xml/System.Data/DataRowView.xml
@@ -418,7 +418,7 @@
         <summary>Returns a <see cref="T:System.Data.DataView" /> for the child <see cref="T:System.Data.DataTable" /> with the specified <see cref="T:System.Data.DataRelation" /> name and parent.</summary>
         <returns>a <see cref="T:System.Data.DataView" /> for the child <see cref="T:System.Data.DataTable" />.</returns>
         <remarks>To be added.</remarks>
-        <exception cref="T:System.ArgumentException">Unmatched <paramref name="relationName" />.</exception>
+        <exception cref="T:System.ArgumentException"><paramref name="relationName" /> could not be matched.</exception>
       </Docs>
     </Member>
     <Member MemberName="DataView">
diff --git a/xml/System.Diagnostics.Metrics/Meter.xml b/xml/System.Diagnostics.Metrics/Meter.xml
@@ -2529,7 +2529,7 @@ UpDownCounter is an Instrument which supports reporting positive or negative met
       </ReturnValue>
       <Docs>
         <summary>
-          <para>The optional schema URL specifies a location of a <see href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/file_format_v1.1.0.md">Schema File</see> that can be retrieved using HTTP or HTTPS protocol.</para>
+          <para>Gets the location of a <see href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/file_format_v1.1.0.md">Schema File</see> that can be retrieved using HTTP or HTTPS protocol.</para>
         </summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
diff --git a/xml/System.Diagnostics.Metrics/MeterOptions.xml b/xml/System.Diagnostics.Metrics/MeterOptions.xml
@@ -147,7 +147,7 @@
       </ReturnValue>
       <Docs>
         <summary>
-          <para>The optional schema URL specifies a location of a <see href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/file_format_v1.1.0.md">Schema File</see> that can be retrieved using HTTP or HTTPS protocol.</para>
+          <para>Gets the location of a <see href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/file_format_v1.1.0.md">Schema File</see> that can be retrieved using HTTP or HTTPS protocol.</para>
         </summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
diff --git a/xml/System.Diagnostics/Activity.xml b/xml/System.Diagnostics/Activity.xml
@@ -279,7 +279,7 @@ Callers should either restrict the number of events added to the same `Activity`
       </Parameters>
       <Docs>
         <param name="link">The <see cref="T:System.Diagnostics.ActivityLink" /> to add.</param>
-        <summary>Add an <see cref="T:System.Diagnostics.ActivityLink" /> to the <see cref="P:System.Diagnostics.Activity.Links" /> list.</summary>
+        <summary>Adds an <see cref="T:System.Diagnostics.ActivityLink" /> to the <see cref="P:System.Diagnostics.Activity.Links" /> list.</summary>
         <returns>
           <see langword="this" /> for convenient chaining.</returns>
         <remarks>
diff --git a/xml/System.Diagnostics/ActivityListener.xml b/xml/System.Diagnostics/ActivityListener.xml
@@ -165,7 +165,7 @@
         <ReturnType>System.Diagnostics.ExceptionRecorder</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Set or get the callback used to listen to <see cref="T:System.Diagnostics.Activity" /> events when exceptions are added.</summary>
+        <summary>Gets or sets the callback used to listen to <see cref="T:System.Diagnostics.Activity" /> events when exceptions are added.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
diff --git a/xml/System.Diagnostics/ActivitySource.xml b/xml/System.Diagnostics/ActivitySource.xml
@@ -50,7 +50,7 @@
       </Parameters>
       <Docs>
         <param name="options">The <see cref="T:System.Diagnostics.ActivitySourceOptions" /> object to use for initializing the ActivitySource object.</param>
-        <summary>Initialize a new instance of the ActivitySource object using the <see cref="T:System.Diagnostics.ActivitySourceOptions" />.</summary>
+        <summary>Initializes a new instance of <see cref="T:System.Diagnostics.ActivitySource" /> using the <see cref="T:System.Diagnostics.ActivitySourceOptions" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -72,7 +72,7 @@
       </Parameters>
       <Docs>
         <param name="name">The name of the ActivitySource object</param>
-        <summary>Construct an ActivitySource object with the input name</summary>
+        <summary>Initializes a new instance of <see cref="T:System.Diagnostics.ActivitySource" /> with the specified input name.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -148,10 +148,10 @@
         </Parameter>
       </Parameters>
       <Docs>
-        <param name="name">The name of the ActivitySource object</param>
+        <param name="name">The name of the ActivitySource object.</param>
         <param name="version">The version of the component publishing the tracing info.</param>
         <param name="tags">The optional ActivitySource tags.</param>
-        <summary>Construct an ActivitySource object with the input name</summary>
+        <summary>Initializes a new instance of <see cref="T:System.Diagnostics.ActivitySource" /> with the specified input name.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -672,7 +672,7 @@ If the Activity object is created, it will not start automatically. Callers need
         <ReturnType>System.Collections.Generic.IEnumerable&lt;System.Collections.Generic.KeyValuePair&lt;System.String,System.Object&gt;&gt;</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Returns the tags associated with the ActivitySource.</summary>
+        <summary>Gets the tags associated with the ActivitySource.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -699,7 +699,7 @@ If the Activity object is created, it will not start automatically. Callers need
         <ReturnType>System.String</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Returns the telemetry schema URL associated with the ActivitySource.</summary>
+        <summary>Gets the telemetry schema URL associated with the ActivitySource.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
diff --git a/xml/System.Diagnostics/ActivitySourceOptions.xml b/xml/System.Diagnostics/ActivitySourceOptions.xml
@@ -20,7 +20,7 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>Options for creating a <see cref="T:System.Diagnostics.ActivitySource" />.</summary>
+    <summary>Options for creating an <see cref="T:System.Diagnostics.ActivitySource" />.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -67,7 +67,7 @@
         <ReturnType>System.String</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Get or set the <see cref="T:System.Diagnostics.ActivitySourceOptions" /> object name. Cannot be <see langword="null" />.</summary>
+        <summary>Gets or sets the <see cref="T:System.Diagnostics.ActivitySourceOptions" /> object name. Cannot be <see langword="null" />.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -94,7 +94,7 @@
         <ReturnType>System.Collections.Generic.IEnumerable&lt;System.Collections.Generic.KeyValuePair&lt;System.String,System.Object&gt;&gt;</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>The optional list of key-value pair tags associated with the <see cref="T:System.Diagnostics.ActivitySourceOptions" />.</summary>
+        <summary>Gets or sets the optional list of key-value pair tags associated with the <see cref="T:System.Diagnostics.ActivitySourceOptions" />.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -116,7 +116,7 @@
       </ReturnValue>
       <Docs>
         <summary>
-          <para>The optional schema URL specifies a location of a <see href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/file_format_v1.1.0.md">Schema File</see> that can be retrieved using HTTP or HTTPS protocol.</para>
+          <para>Gets or sets the location of a <see href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/file_format_v1.1.0.md">Schema file</see> that can be retrieved using HTTP or HTTPS protocol.</para>
         </summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
@@ -138,8 +138,8 @@
         <ReturnType>System.String</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>The optional <see cref="T:System.Diagnostics.ActivitySourceOptions" /> version. Defaulted to empty string.</summary>
-        <value>To be added.</value>
+        <summary>Gets or sets the <see cref="T:System.Diagnostics.ActivitySourceOptions" /> version.</summary>
+        <value>The <see cref="T:System.Diagnostics.ActivitySourceOptions" /> version. The default value is the empty string.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
diff --git a/xml/System.Diagnostics/ExceptionRecorder.xml b/xml/System.Diagnostics/ExceptionRecorder.xml
@@ -25,7 +25,7 @@
     <param name="activity">To be added.</param>
     <param name="exception">To be added.</param>
     <param name="tags">To be added.</param>
-    <summary>Define the callback to be used in <see cref="T:System.Diagnostics.ActivityListener" /> to receive notifications when exceptions are added to the <see cref="T:System.Diagnostics.Activity" />.</summary>
+    <summary>Defines the callback to be used in <see cref="T:System.Diagnostics.ActivityListener" /> to receive notifications when exceptions are added to the <see cref="T:System.Diagnostics.Activity" />.</summary>
     <remarks>To be added.</remarks>
   </Docs>
 </Type>
diff --git a/xml/System.Diagnostics/ProcessStartInfo.xml b/xml/System.Diagnostics/ProcessStartInfo.xml
@@ -223,7 +223,7 @@
         <param name="fileName">To be added.</param>
         <param name="arguments">To be added.</param>
         <summary>
-          <para>Specifies the name of the application that is to be started, as well as a set of command line arguments to pass to the application.</para>
+          <para>Initializes a new instance of the <see cref="T:System.Diagnostics.ProcessStartInfo" /> class and specifies the name of the application to start and a set of command-line arguments to pass to the application.</para>
         </summary>
         <remarks>To be added.</remarks>
       </Docs>
@@ -484,10 +484,10 @@ If you use this property to set command-line arguments, <xref:System.Diagnostics
       <Docs>
         <summary>Gets or sets a value indicating whether to start the process in a new process group.</summary>
         <value>
-          <see langword="true" /> if the process should be started in a new process group; otherwise, <see langword="false" />. The default is <see langword="false" />.</value>
+          <see langword="true" /> if the process starts in a new process group; otherwise, <see langword="false" />. The default is <see langword="false" />.</value>
         <remarks>
           <para>When a process is created in a new process group, it becomes the root of a new process group.</para>
-          <para>An implicit call to <c>SetConsoleCtrlHandler(NULL,TRUE)</c> is made on behalf of the new process, this means that the new process has CTRL+C disabled.</para>
+          <para>An implicit call to <c>SetConsoleCtrlHandler(NULL,TRUE)</c> is made on behalf of the new process, which means that the new process has Ctrl+C disabled.</para>
           <para>This property is useful for preventing console control events sent to the child process from affecting the parent process.</para>
         </remarks>
       </Docs>
@@ -1741,11 +1741,10 @@ You can use asynchronous read operations to avoid these dependencies and their d
       </ReturnValue>
       <Docs>
         <summary>
-          <para>Gets or sets a value that indicates whether the user credentials are only to be used for network resources.</para>
+          Gets or sets a value that indicates whether the user credentials are only used for network resources.
         </summary>
         <value>
-          <para>
-            <see langword="true" /> if the user credentials are only to be used for network resources.</para>
+          <see langword="true" /> if the user credentials are only used for network resources; otherwise, <see langword="false" />.
         </value>
         <remarks><para>This property is referenced if the process is being started by using the user name, password, and domain.</para><para>If the value is <see langword="true" />, the process is started with the caller's identity. The system creates a new logon session with the given credentials, which is used on the network only.</para><para>The system does not validate the specified credentials. Therefore, the process can start, but it may not have access to network resources.</para></remarks>
       </Docs>
diff --git a/xml/System.DirectoryServices.Protocols/LdapSessionOptions.xml b/xml/System.DirectoryServices.Protocols/LdapSessionOptions.xml
@@ -615,10 +615,9 @@
       <Parameters />
       <Docs>
         <summary>
-          <para>Create a new TLS library context.</para>
-          <para>Calling this is necessary after setting TLS-based options, such as <c>TrustedCertificatesDirectory</c>.</para>
+          Creates a new TLS library context.
         </summary>
-        <remarks>To be added.</remarks>
+        <remarks>It's necessary to call this method after setting TLS-based options, such as <c>TrustedCertificatesDirectory</c>.</remarks>
       </Docs>
     </Member>
     <Member MemberName="StartTransportLayerSecurity">
@@ -722,13 +721,13 @@
       </ReturnValue>
       <Docs>
         <summary>
-          <para>Specifies the path of the directory containing CA certificates in the PEM format.</para>
-          <para>Multiple directories may be specified by separating with a semi-colon.</para>
+          Gets or sets the path of the directory containing CA certificates in the PEM format.
         </summary>
         <value>To be added.</value>
         <remarks>
-          <para>The certificate files are looked up by the CA subject name hash value where that hash can be obtained by using, for example, <code>openssl x509 -hash -noout -in CA.crt</code>.</para>
-          <para>It is a common practice to have the certificate file be a symbolic link to the actual certificate file which can be done by using <code>openssl rehash .</code> or <code>c_rehash .</code> in the directory containing the certificate files.</para>
+          <para>Multiple directories can be specified by separating them with a semi-colon.</para>
+          <para>The certificate files are looked up by the CA subject name hash value. The hash can be obtained by using, for example, <code>openssl x509 -hash -noout -in CA.crt</code>.</para>
+          <para>It is a common practice to have the certificate file be a symbolic link to the actual certificate file, which can be done by using <code>openssl rehash .</code> or <code>c_rehash .</code> in the directory containing the certificate files.</para>
         </remarks>
         <exception cref="T:System.IO.DirectoryNotFoundException">The directory does not exist.</exception>
       </Docs>
