Merge main into live (#7368)

* Update IConfiguration.xml Add a additional remark paragraph * Mention C# native integers in IntPtr/UIntPtr docs (#7364) * Update IntPtr.xml * Update UIntPtr.xml * Fixed identation (#7365) * Update xml/Microsoft.Extensions.Configuration/IConfiguration.xml The grammar is resolved Co-authored-by: Eric Erhardt <eric.erhardt@microsoft.com> * Update obsoletion note in summary (#7359) * Update SecureString.xml (#7344) Obviously, those duplicate `SecureStringToCoTaskMemUnicode` should be `SecureStringToGlobalAllocUnicode` * Add exception (#7360) * add new exceptions (#7367) Co-authored-by: Artur <58558002+Narick9@users.noreply.github.com> Co-authored-by: MSDN.WhiteKnight <35516665+MSDN-WhiteKnight@users.noreply.github.com> Co-authored-by: Thiago Viana Avelar De Souza <thide2001@gmail.com> Co-authored-by: Eric Erhardt <eric.erhardt@microsoft.com> Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Co-authored-by: tangentyh <tangentyh@users.noreply.github.com>
dotnet · Nov 9, 2021 · ff61351 · ff61351
1 parent 5b4c9aa
commit ff61351
Show file tree

Hide file tree

Showing 9 changed files with 60 additions and 49 deletions.
diff --git a/...sharp/VS_Snippets_CLR_System/system.threading.cancellationtokensource.class/cs/cancel1.cs b/...sharp/VS_Snippets_CLR_System/system.threading.cancellationtokensource.class/cs/cancel1.cs
@@ -20,43 +20,43 @@ public static void Main()
       for (int taskCtr = 0; taskCtr <= 10; taskCtr++) {
          int iteration = taskCtr + 1;
          tasks.Add(factory.StartNew( () => {
-                                       int value;
-                                       int[] values = new int[10];
-                                       for (int ctr = 1; ctr <= 10; ctr++) {
-                                          lock (lockObj) {
-                                             value = rnd.Next(0,101);
-                                          }
-                                          if (value == 0) { 
-                                             source.Cancel();
-                                             Console.WriteLine("Cancelling at task {0}", iteration);
-                                             break;
-                                          }   
-                                          values[ctr-1] = value; 
-                                       }
-                                       return values;
-                                    }, token));   
+           int value;
+           int[] values = new int[10];
+           for (int ctr = 1; ctr <= 10; ctr++) {
+              lock (lockObj) {
+                 value = rnd.Next(0,101);
+              }
+              if (value == 0) { 
+                 source.Cancel();
+                 Console.WriteLine("Cancelling at task {0}", iteration);
+                 break;
+              }   
+              values[ctr-1] = value; 
+           }
+           return values;
+        }, token));   
       }
       try {
          Task<double> fTask = factory.ContinueWhenAll(tasks.ToArray(), 
-                                                      (results) => {
-                                                         Console.WriteLine("Calculating overall mean...");
-                                                         long sum = 0;
-                                                         int n = 0; 
-                                                         foreach (var t in results) {
-                                                            foreach (var r in t.Result) {
-                                                                  sum += r;
-                                                                  n++;
-                                                               }
-                                                         }
-                                                         return sum/(double) n;
-                                                      } , token);
+         (results) => {
+            Console.WriteLine("Calculating overall mean...");
+            long sum = 0;
+            int n = 0; 
+            foreach (var t in results) {
+               foreach (var r in t.Result) {
+                  sum += r;
+                  n++;
+               }
+            }
+            return sum/(double) n;
+         } , token);
          Console.WriteLine("The mean is {0}.", fTask.Result);
       }   
       catch (AggregateException ae) {
          foreach (Exception e in ae.InnerExceptions) {
             if (e is TaskCanceledException)
                Console.WriteLine("Unable to compute mean: {0}", 
-                                 ((TaskCanceledException) e).Message);
+                  ((TaskCanceledException) e).Message);
             else
                Console.WriteLine("Exception: " + e.GetType().Name);
          }
@@ -99,4 +99,4 @@ public static void Main()
 //       
 //       Calculating overall mean...
 //       The mean is 4.86545454545455.
-// </Snippet1>
+// </Snippet1>
diff --git a/xml/Microsoft.Extensions.Configuration/IConfiguration.xml b/xml/Microsoft.Extensions.Configuration/IConfiguration.xml
@@ -114,7 +114,9 @@
         <summary>Gets a configuration sub-section with the specified key.</summary>
         <returns>The <see cref="T:Microsoft.Extensions.Configuration.IConfigurationSection" />.</returns>
         <remarks>This method will never return <see langword="null" />. If no matching sub-section is found with the specified key,
-                an empty <see cref="T:Microsoft.Extensions.Configuration.IConfigurationSection" /> will be returned.</remarks>
+                an empty <see cref="T:Microsoft.Extensions.Configuration.IConfigurationSection" /> will be returned.
+
+                You can reach a sub-subsection by passing "section1:section2:section.." for <paramref name="key"/>.</remarks>
       </Docs>
     </Member>
     <Member MemberName="Item">

diff --git a/xml/Microsoft.Extensions.DependencyInjection/ISupportRequiredService.xml b/xml/Microsoft.Extensions.DependencyInjection/ISupportRequiredService.xml
@@ -19,8 +19,7 @@
   </AssemblyInfo>
   <Interfaces />
   <Docs>
-    <summary>Optional contract used by <see cref="M:Microsoft.Extensions.DependencyInjection.ServiceProviderServiceExtensions.GetRequiredService``1(System.IServiceProvider)" />
-            to resolve services if supported by <see cref="T:System.IServiceProvider" />.</summary>
+    <summary>Optional contract used by <see cref="M:Microsoft.Extensions.DependencyInjection.ServiceProviderServiceExtensions.GetRequiredService``1(System.IServiceProvider)" /> to resolve services if supported by <see cref="T:System.IServiceProvider" />.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -51,12 +50,12 @@
         <Parameter Name="serviceType" Type="System.Type" />
       </Parameters>
       <Docs>
-        <param name="serviceType">An object that specifies the type of service object to get.</param>
-        <summary>Gets service of type <paramref name="serviceType" /> from the <see cref="T:System.IServiceProvider" /> implementing
-            this interface.</summary>
-        <returns>A service object of type <paramref name="serviceType" />.
-            Throws an exception if the <see cref="T:System.IServiceProvider" /> cannot create the object.</returns>
+        <param name="serviceType">The type of service object to get.</param>
+        <summary>Gets service of type <paramref name="serviceType" /> from the <see cref="T:System.IServiceProvider" /> that implements this interface.</summary>
+        <returns>A service object of type <paramref name="serviceType" />. Throws an exception if the <see cref="T:System.IServiceProvider" /> cannot create the object.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ObjectDisposedException">
+          <paramref name="provider" /> has already been disposed.</exception>
       </Docs>
     </Member>
   </Members>

diff --git a/xml/Microsoft.Extensions.DependencyInjection/ServiceProviderServiceExtensions.xml b/xml/Microsoft.Extensions.DependencyInjection/ServiceProviderServiceExtensions.xml
@@ -142,6 +142,8 @@
         <returns>A service object of type <paramref name="serviceType" />.</returns>
         <remarks>To be added.</remarks>
         <exception cref="T:System.InvalidOperationException">There is no service of type <paramref name="serviceType" />.</exception>
+        <exception cref="T:System.ObjectDisposedException">
+          <paramref name="provider" /> has already been disposed.</exception>
       </Docs>
     </Member>
     <Member MemberName="GetRequiredService&lt;T&gt;">
@@ -180,6 +182,8 @@
         <returns>A service object of type <typeparamref name="T" />.</returns>
         <remarks>To be added.</remarks>
         <exception cref="T:System.InvalidOperationException">There is no service of type <typeparamref name="T" />.</exception>
+        <exception cref="T:System.ObjectDisposedException">
+          <paramref name="provider" /> has already been disposed.</exception>
       </Docs>
     </Member>
     <Member MemberName="GetService&lt;T&gt;">

diff --git a/xml/Microsoft.Extensions.Logging/LoggerFactory.xml b/xml/Microsoft.Extensions.Logging/LoggerFactory.xml
@@ -29,7 +29,7 @@
     </Interface>
   </Interfaces>
   <Docs>
-    <summary>Produces instances of <see cref="T:Microsoft.Extensions.Logging.ILogger" /> classes based on the given providers.</summary>
+    <summary>Produces instances of <see cref="T:Microsoft.Extensions.Logging.ILogger" /> classes based on the specified providers.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -81,7 +81,7 @@
       </Parameters>
       <Docs>
         <param name="providers">The providers to use in producing <see cref="T:Microsoft.Extensions.Logging.ILogger" /> instances.</param>
-        <summary>Creates a new <see cref="T:Microsoft.Extensions.Logging.LoggerFactory" /> instance.</summary>
+        <summary>Creates a new <see cref="T:Microsoft.Extensions.Logging.LoggerFactory" /> instance with the specified providers.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -110,7 +110,7 @@
       <Docs>
         <param name="providers">The providers to use in producing <see cref="T:Microsoft.Extensions.Logging.ILogger" /> instances.</param>
         <param name="filterOptions">The filter options to use.</param>
-        <summary>Creates a new <see cref="T:Microsoft.Extensions.Logging.LoggerFactory" /> instance.</summary>
+        <summary>Creates a new <see cref="T:Microsoft.Extensions.Logging.LoggerFactory" /> instance with the specified providers and filter options.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -139,7 +139,7 @@
       <Docs>
         <param name="providers">The providers to use in producing <see cref="T:Microsoft.Extensions.Logging.ILogger" /> instances.</param>
         <param name="filterOption">The filter option to use.</param>
-        <summary>Creates a new <see cref="T:Microsoft.Extensions.Logging.LoggerFactory" /> instance.</summary>
+        <summary>Creates a new <see cref="T:Microsoft.Extensions.Logging.LoggerFactory" /> instance with the specified providers and filter option.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -164,7 +164,7 @@
         <param name="providers">The providers to use in producing <see cref="T:Microsoft.Extensions.Logging.ILogger" /> instances.</param>
         <param name="filterOption">The filter option to use.</param>
         <param name="options">The logger factory options.</param>
-        <summary>Creates a new <see cref="T:Microsoft.Extensions.Logging.LoggerFactory" /> instance with the specified providers, filter option and logger factory options.</summary>
+        <summary>Creates a new <see cref="T:Microsoft.Extensions.Logging.LoggerFactory" /> instance with the specified providers, filter option, and logger factory options.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -199,8 +199,10 @@
       </Parameters>
       <Docs>
         <param name="provider">The <see cref="T:Microsoft.Extensions.Logging.ILoggerProvider" /> to add.</param>
-        <summary>Adds the given provider to those used in creating <see cref="T:Microsoft.Extensions.Logging.ILogger" /> instances.</summary>
+        <summary>Adds the specified provider to the collection of providers used in creating <see cref="T:Microsoft.Extensions.Logging.ILogger" /> instances.</summary>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException">
+          <paramref name="provider" /> is <see langword="null" />.</exception>
       </Docs>
     </Member>
     <Member MemberName="CheckDisposed">
@@ -227,7 +229,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>Check if the factory has been disposed.</summary>
+        <summary>Checks if the factory has been disposed.</summary>
         <returns>
           <see langword="true" /> if <see cref="M:Microsoft.Extensions.Logging.LoggerFactory.Dispose" /> has been called; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
@@ -256,7 +258,7 @@
       </Parameters>
       <Docs>
         <param name="configure">A delegate to configure the <see cref="T:Microsoft.Extensions.Logging.ILoggingBuilder" />.</param>
-        <summary>Creates new instance of <see cref="T:Microsoft.Extensions.Logging.ILoggerFactory" /> configured using provided <paramref name="configure" /> delegate.</summary>
+        <summary>Creates a new instance of <see cref="T:Microsoft.Extensions.Logging.ILoggerFactory" /> that's configured using the provided <paramref name="configure" /> delegate.</summary>
         <returns>The <see cref="T:Microsoft.Extensions.Logging.ILoggerFactory" /> that was created.</returns>
         <remarks>To be added.</remarks>
       </Docs>
@@ -292,7 +294,7 @@
       </Parameters>
       <Docs>
         <param name="categoryName">The category name for messages produced by the logger.</param>
-        <summary>Creates an <see cref="T:Microsoft.Extensions.Logging.ILogger" /> with the given <paramref name="categoryName" />.</summary>
+        <summary>Creates an <see cref="T:Microsoft.Extensions.Logging.ILogger" /> with the specified <paramref name="categoryName" />.</summary>
         <returns>The <see cref="T:Microsoft.Extensions.Logging.ILogger" /> that was created.</returns>
         <remarks>To be added.</remarks>
       </Docs>

diff --git a/xml/System.Net.Mail/SmtpClient.xml b/xml/System.Net.Mail/SmtpClient.xml
@@ -52,7 +52,7 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>Allows applications to send email by using the Simple Mail Transfer Protocol (SMTP). The <c>SmtpClient</c> type is now obsolete.</summary>
+    <summary>Allows applications to send email by using the Simple Mail Transfer Protocol (SMTP). The <see cref="T:System.Net.Mail.SmtpClient" /> type is obsolete on some platforms and not recommended on others; for more information, see the Remarks section.</summary>
     <remarks>
       <format type="text/markdown"><![CDATA[  
   

diff --git a/xml/System.Security/SecureString.xml b/xml/System.Security/SecureString.xml
@@ -129,7 +129,7 @@
   
 -   <xref:System.Runtime.InteropServices.Marshal.SecureStringToCoTaskMemAnsi%2A?displayProperty=nameWithType> and <xref:System.Runtime.InteropServices.Marshal.SecureStringToGlobalAllocAnsi%2A?displayProperty=nameWithType>, which copy the <xref:System.Security.SecureString> string value to an ANSI string in unmanaged memory.  
   
--   <xref:System.Runtime.InteropServices.Marshal.SecureStringToCoTaskMemUnicode%2A?displayProperty=nameWithType> and <xref:System.Runtime.InteropServices.Marshal.SecureStringToCoTaskMemUnicode%2A?displayProperty=nameWithType>, which copy the <xref:System.Security.SecureString> string value to a Unicode string in unmanaged memory.  
+-   <xref:System.Runtime.InteropServices.Marshal.SecureStringToCoTaskMemUnicode%2A?displayProperty=nameWithType> and <xref:System.Runtime.InteropServices.Marshal.SecureStringToGlobalAllocUnicode%2A?displayProperty=nameWithType>, which copy the <xref:System.Security.SecureString> string value to a Unicode string in unmanaged memory.  
   
  Each of these methods creates a clear-text string in unmanaged memory. It is the responsibility of the developer to zero out and free that memory as soon as it is no longer needed. Each of the string conversion and memory allocation methods has a corresponding method to zero out and free the allocated memory:  
   
@@ -139,7 +139,7 @@
 |<xref:System.Runtime.InteropServices.Marshal.SecureStringToCoTaskMemAnsi%2A?displayProperty=nameWithType>|<xref:System.Runtime.InteropServices.Marshal.ZeroFreeCoTaskMemAnsi%2A?displayProperty=nameWithType>|  
 |<xref:System.Runtime.InteropServices.Marshal.SecureStringToCoTaskMemUnicode%2A?displayProperty=nameWithType>|<xref:System.Runtime.InteropServices.Marshal.ZeroFreeCoTaskMemUnicode%2A?displayProperty=nameWithType>|  
 |<xref:System.Runtime.InteropServices.Marshal.SecureStringToGlobalAllocAnsi%2A?displayProperty=nameWithType>|<xref:System.Runtime.InteropServices.Marshal.ZeroFreeGlobalAllocAnsi%2A?displayProperty=nameWithType>|  
-|<xref:System.Runtime.InteropServices.Marshal.SecureStringToCoTaskMemUnicode%2A?displayProperty=nameWithType>|<xref:System.Runtime.InteropServices.Marshal.ZeroFreeGlobalAllocUnicode%2A?displayProperty=nameWithType>|  
+|<xref:System.Runtime.InteropServices.Marshal.SecureStringToGlobalAllocUnicode%2A?displayProperty=nameWithType>|<xref:System.Runtime.InteropServices.Marshal.ZeroFreeGlobalAllocUnicode%2A?displayProperty=nameWithType>|  
   
  [Back to top](#top)  
   

diff --git a/xml/System/IntPtr.xml b/xml/System/IntPtr.xml
@@ -107,6 +107,8 @@
  The <xref:System.IntPtr> type is CLS-compliant, while the <xref:System.UIntPtr> type is not. Only the <xref:System.IntPtr> type is used in the common language runtime. The <xref:System.UIntPtr> type is provided mostly to maintain architectural symmetry with the <xref:System.IntPtr> type.  
   
  This type implements the <xref:System.Runtime.Serialization.ISerializable>, and, in .NET 5.0 and later, the <xref:System.IFormattable> interfaces.
+ 
+ In C# starting from version 9.0, you can use the built-in `nint` type to define native-sized integers. This type is represented by the <xref:System.IntPtr> type internally and provides operations and conversions that are appropriate for integer types. For more information, see [nint and nuint types](/dotnet/csharp/language-reference/builtin-types/nint-nuint).
   
 ## Examples
 

diff --git a/xml/System/UIntPtr.xml b/xml/System/UIntPtr.xml
@@ -110,6 +110,8 @@
  The <xref:System.UIntPtr> type can be used by languages that support pointers, and as a common means of referring to data between languages that do and do not support pointers. <xref:System.UIntPtr> objects can also be used to hold handles.  
   
  This type implements the <xref:System.Runtime.Serialization.ISerializable>, and, in .NET 5.0 and later, the <xref:System.IFormattable> interfaces.
+ 
+ In C# starting from version 9.0, you can use the built-in `nuint` type to define native-sized integers. This type is represented by the <xref:System.UIntPtr> type internally and provides operations and conversions that are appropriate for integer types. For more information, see [nint and nuint types](/dotnet/csharp/language-reference/builtin-types/nint-nuint).
   
  ]]></format>
     </remarks>