Merge pull request #4212 from dotnet/publish-18568

Merge master into live

Author: gewarren

samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.semaphoreslim/cs/example.cs

@@ -16,25 +16,27 @@ public static void Main()
         Console.WriteLine("{0} tasks can enter the semaphore.",
                           semaphore.CurrentCount);
         Task[] tasks = new Task[5];
-        
+
         // Create and start five numbered tasks.
-        for(int i = 0; i <= 4; i++)
+        for (int i = 0; i <= 4; i++)
         {
-            tasks[i] = Task.Run( () => {
-            // Each task begins by requesting the semaphore.
-            Console.WriteLine("Task {0} begins and waits for the semaphore.",
-                              Task.CurrentId);
-            semaphore.Wait();
+            tasks[i] = Task.Run(() =>
+            {
+                // Each task begins by requesting the semaphore.
+                Console.WriteLine("Task {0} begins and waits for the semaphore.",
+                                  Task.CurrentId);
+                semaphore.Wait();
 
-            Interlocked.Add(ref padding, 100);
+                Interlocked.Add(ref padding, 100);
 
-            Console.WriteLine("Task {0} enters the semaphore.", Task.CurrentId);
+                Console.WriteLine("Task {0} enters the semaphore.", Task.CurrentId);
 
-            // The task just sleeps for 1+ seconds.
-            Thread.Sleep(1000 + padding);
+                // The task just sleeps for 1+ seconds.
+                Thread.Sleep(1000 + padding);
 
-            Console.WriteLine("Task {0} releases the semaphore; previous count: {1}.",
-                              Task.CurrentId, semaphore.Release()); } );
+                Console.WriteLine("Task {0} releases the semaphore; previous count: {1}.",
+                                  Task.CurrentId, semaphore.Release());
+            });
         }
 
         // Wait for half a second, to allow all the tasks to start and block.
@@ -47,7 +49,7 @@ public static void Main()
                           semaphore.CurrentCount);
         // Main thread waits for the tasks to complete.
         Task.WaitAll(tasks);
-        
+
         Console.WriteLine("Main thread exits.");
     }
 }

xml/System.Threading/CancellationTokenRegistration.xml

@@ -450,12 +450,17 @@ The returned <xref:System.Threading.Tasks.ValueTask> completes once the associat
         <ReturnType>System.Threading.CancellationToken</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets the <see cref="T:System.Threading.CancellationToken" /> with which this registration is associated.  If the
-            registration isn't associated with a token (such as after the registration has been disposed),
-            this will return a default token.</summary>
+        <summary>Gets the <see cref="T:System.Threading.CancellationToken" /> with which this registration is associated.</summary>
         <value>The cancellation token with which this registration is associated, or a default token if the
-            registration isn't associated with a token (such as after the registration has been disposed).</value>
-        <remarks>To be added.</remarks>
+            registration isn't associated with a token.</value>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+
+If the <xref:System.Threading.CancellationTokenRegistration> was created by registering with a <xref:System.Threading.CancellationToken> that already
+had cancellation requested, the registration may not be associated with the token, in which case this property may return a default token.
+
+         ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Unregister">

xml/System/String.xml

@@ -98,6 +98,8 @@
 
  A string is a sequential collection of characters that is used to represent text. A <xref:System.String> object is a sequential collection of <xref:System.Char?displayProperty=nameWithType> objects that represent a string; a <xref:System.Char?displayProperty=nameWithType> object corresponds to a UTF-16 code unit. The value of the <xref:System.String> object is the content of the sequential collection of <xref:System.Char?displayProperty=nameWithType> objects, and that value is immutable (that is, it is read-only). For more information about the immutability of strings, see the [Immutability and the StringBuilder class](#Immutability) section later in this topic. The maximum size of a <xref:System.String> object in memory is 2GB, or about 1 billion characters.
 
+For more information about Unicode, UTF-16, code units, code points, and the <xref:System.Char> and <xref:System.Text.Rune> types, see [Introduction to character encoding in .NET](/dotnet/standard/base-types/character-encoding-introduction).
+
  In this section:
 
  [Instantiate a String object](#Instantiation)\
@@ -214,15 +216,15 @@
  [!code-csharp-interactive[System.String.Class#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Class/cs/index2.cs#5)]
  [!code-vb[System.String.Class#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Class/vb/index2.vb#5)]
 
- Consecutive index values might not correspond to consecutive Unicode characters, because a Unicode character might be encoded as more than one <xref:System.Char> object. In particular, a string may contain multi-character units of text that are formed by a base character followed by one or more combining characters or by surrogate pairs. To work with Unicode characters instead of <xref:System.Char> objects, use the <xref:System.Globalization.StringInfo?displayProperty=nameWithType> and <xref:System.Globalization.TextElementEnumerator> classes. The following example illustrates the difference between code that works with <xref:System.Char> objects and code that works with Unicode characters. It compares the number of characters or text elements in each word of a sentence. The string includes two sequences of a base character followed by a combining character.
+ Consecutive index values might not correspond to consecutive Unicode characters, because a Unicode character might be encoded as more than one <xref:System.Char> object. In particular, a string may contain multi-character units of text that are formed by a base character followed by one or more combining characters or by surrogate pairs. To work with Unicode characters instead of <xref:System.Char> objects, use the <xref:System.Globalization.StringInfo?displayProperty=nameWithType> and <xref:System.Globalization.TextElementEnumerator> classes, or the <xref:System.String.EnumerateRunes%2A?displayProperty=nameWithType> method and the <xref:System.Text.Rune> type. The following example illustrates the difference between code that works with <xref:System.Char> objects and code that works with Unicode characters. It compares the number of characters or text elements in each word of a sentence. The string includes two sequences of a base character followed by a combining character.
 
  [!code-cpp[System.String.Class#6](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.String.Class/cpp/string.index3.cpp#6)]
  [!code-csharp-interactive[System.String.Class#6](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Class/cs/index3.cs#6)]
  [!code-vb[System.String.Class#6](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Class/vb/index3.vb#6)]
 
  This example works with text elements by using the <xref:System.Globalization.StringInfo.GetTextElementEnumerator%2A?displayProperty=nameWithType> method and the <xref:System.Globalization.TextElementEnumerator> class to enumerate all the text elements in a string. You can also retrieve an array that contains the starting index of each text element by calling the <xref:System.Globalization.StringInfo.ParseCombiningCharacters%2A?displayProperty=nameWithType> method.
 
- For more information about working with units of text rather than individual <xref:System.Char> values, see the <xref:System.Globalization.StringInfo> class.
+ For more information about working with units of text rather than individual <xref:System.Char> values, see [Introduction to character encoding in .NET](/dotnet/standard/base-types/character-encoding-introduction).
 
 <a name="Nulls"></a>
 ## Null strings and empty strings