Merge pull request #4117 from dotnet/publish-13633

Merge master into live

Author: BillWagner

xml/System.Collections.Generic/List`1.xml

@@ -4317,7 +4317,7 @@ SyncLock ic.SyncRoot
 End SyncLock  
 ```  
   
-```cpp#  
+```cpp
 ICollection^ ic = ...;  
 try   
 {  

xml/System.Text/Decoder.xml

@@ -172,7 +172,7 @@ Any remaining processed data that is part of a logical unit, such as the high su
 
 The `Convert` method is designed to be used in a loop to decode an arbitrary amount of input, such as data read from a file or stream. 
 It stores the output of the decoding operation in a fixed-size buffer.
-<xref:System.Text.Decoder.GetChars%2A> will throw an exception if the output buffer isn't large enough, but <xref:System.Text.Decoder.Convert%2A> will fill as much space as possible and return the bytes read and chars written. 
+<xref:System.Text.Decoder.GetChars%2A> will throw an exception if the output buffer isn't large enough, but <xref:System.Text.Decoder.Convert%2A> will fill as much space as possible and return the bytes read and chars written, provided the output array allows for at least two characters. 
 Also see <xref:System.Text.Encoding.GetChars%2A?displayProperty=nameWithType> for more comments.
 
  ]]></format>
@@ -315,7 +315,7 @@ The `completed` parameter can also be set to `false`, even though the `bytesUsed
           <paramref name="chars" /> or <paramref name="bytes" /> is <see langword="null" /> (<see langword="Nothing" />).</exception>
         <exception cref="T:System.ArgumentOutOfRangeException">
           <paramref name="charCount" /> or <paramref name="byteCount" /> is less than zero.</exception>
-        <exception cref="T:System.ArgumentException">The output buffer is too small to contain any of the converted input. The output buffer should be greater than or equal to the size indicated by the <see cref="Overload:System.Text.Decoder.GetCharCount" /> method.</exception>
+        <exception cref="T:System.ArgumentException">The output buffer is too small to contain any of the converted input. The output buffer should be at least 2 chars in size to accomodate at least one surrogate character pair.</exception>
         <exception cref="T:System.Text.DecoderFallbackException">A fallback occurred (for more information, see <see href="~/docs/standard/base-types/character-encoding.md">Character Encoding in .NET</see>)
 
  -and-
@@ -417,7 +417,7 @@ The following example uses the <xref:System.Text.Encoder.Convert%2A> method to c
  -or-
 
  The length of <paramref name="bytes" /> - <paramref name="byteIndex" /> is less than <paramref name="byteCount" />.</exception>
-        <exception cref="T:System.ArgumentException">The output buffer is too small to contain any of the converted input. The output buffer should be greater than or equal to the size indicated by the <see cref="Overload:System.Text.Decoder.GetCharCount" /> method.</exception>
+        <exception cref="T:System.ArgumentException">The output buffer is too small to contain any of the converted input. The output buffer should be at least 2 chars in size to accomodate at least one surrogate character pair.</exception>
         <exception cref="T:System.Text.DecoderFallbackException">A fallback occurred (for more information, see <see href="~/docs/standard/base-types/character-encoding.md">Character Encoding in .NET</see>)
 
  -and-
@@ -898,7 +898,7 @@ The following example uses the <xref:System.Text.Encoder.Convert%2A> method to c
 
  If `GetChars` is called with `flush` set to `false`, the decoder stores trailing bytes at the end of the data block in an internal buffer and uses them in the next decoding operation. The application should call `GetCharCount` on a block of data immediately before calling `GetChars` on the same block, so that any trailing bytes from the previous block are included in the calculation.
 
- If your application is to convert many segments of an input stream, consider using the <xref:System.Text.Decoder.Convert%2A> method. <xref:System.Text.Decoder.GetChars%2A> will throw an exception if the output span isn't large enough, but <xref:System.Text.Decoder.Convert%2A> will fill as much space as possible and return the bytes read and chars written. Also see the <xref:System.Text.Encoding.GetChars%2A?displayProperty=nameWithType> topic for more comments.
+ If your application is to convert many segments of an input stream, consider using the <xref:System.Text.Decoder.Convert%2A> method. <xref:System.Text.Decoder.GetChars%2A> will throw an exception if the output span isn't large enough, but <xref:System.Text.Decoder.Convert%2A> will fill as much space as possible and return the bytes read and chars written, provided the output array allows for at least two characters. Also see the <xref:System.Text.Encoding.GetChars%2A?displayProperty=nameWithType> topic for more comments.
 
  ]]></format>
         </remarks>
@@ -972,7 +972,7 @@ The following example uses the <xref:System.Text.Encoder.Convert%2A> method to c
 
  If `GetChars` is called with `flush` set to `false`, the decoder stores trailing bytes at the end of the data block in an internal buffer and uses them in the next decoding operation. The application should call `GetCharCount` on a block of data immediately before calling `GetChars` on the same block, so that any trailing bytes from the previous block are included in the calculation.
 
- If your application is to convert many segments of an input stream, consider using the <xref:System.Text.Decoder.Convert%2A> method. <xref:System.Text.Decoder.GetChars%2A> will throw an exception if the output buffer isn't large enough, but <xref:System.Text.Decoder.Convert%2A> will fill as much space as possible and return the bytes read and chars written. Also see the <xref:System.Text.Encoding.GetChars%2A?displayProperty=nameWithType> topic for more comments.
+ If your application is to convert many segments of an input stream, consider using the <xref:System.Text.Decoder.Convert%2A> method. <xref:System.Text.Decoder.GetChars%2A> will throw an exception if the output buffer isn't large enough, but <xref:System.Text.Decoder.Convert%2A> will fill as much space as possible and return the bytes read and chars written, provided the output array allows for at least two characters. Also see the <xref:System.Text.Encoding.GetChars%2A?displayProperty=nameWithType> topic for more comments.
 
  ]]></format>
         </remarks>
@@ -1055,7 +1055,7 @@ The following example uses the <xref:System.Text.Encoder.Convert%2A> method to c
 
  If `GetChars` is called with `flush` set to `false`, the decoder stores trailing bytes at the end of the data block in an internal buffer and uses them in the next decoding operation. The application should call `GetCharCount` on a block of data immediately before calling `GetChars` on the same block, so that any trailing bytes from the previous block are included in the calculation.
 
- If your application is to convert many segments of an input stream, consider using the <xref:System.Text.Decoder.Convert%2A> method. <xref:System.Text.Decoder.GetChars%2A> will throw an exception if the output buffer isn't large enough, but <xref:System.Text.Decoder.Convert%2A> will fill as much space as possible and return the bytes read and chars written. Also see the <xref:System.Text.Encoding.GetChars%2A?displayProperty=nameWithType> topic for more comments.
+ If your application is to convert many segments of an input stream, consider using the <xref:System.Text.Decoder.Convert%2A> method. <xref:System.Text.Decoder.GetChars%2A> will throw an exception if the output buffer isn't large enough, but <xref:System.Text.Decoder.Convert%2A> will fill as much space as possible and return the bytes read and chars written, provided the output array allows for at least two characters. Also see the <xref:System.Text.Encoding.GetChars%2A?displayProperty=nameWithType> topic for more comments.
 
 
 
@@ -1157,7 +1157,7 @@ The following example uses the <xref:System.Text.Encoder.Convert%2A> method to c
 
  If `GetChars` is called with `flush` set to `false`, the decoder stores trailing bytes at the end of the data block in an internal buffer and uses them in the next decoding operation. The application should call `GetCharCount` on a block of data immediately before calling `GetChars` on the same block, so that any trailing bytes from the previous block are included in the calculation.
 
- If your application is to convert many segments of an input stream, consider using the <xref:System.Text.Decoder.Convert%2A> method. <xref:System.Text.Decoder.GetChars%2A> will throw an exception if the output buffer isn't large enough, but <xref:System.Text.Decoder.Convert%2A> will fill as much space as possible and return the bytes read and chars written. Also see the <xref:System.Text.Encoding.GetChars%2A?displayProperty=nameWithType> topic for more comments.
+ If your application is to convert many segments of an input stream, consider using the <xref:System.Text.Decoder.Convert%2A> method. <xref:System.Text.Decoder.GetChars%2A> will throw an exception if the output buffer isn't large enough, but <xref:System.Text.Decoder.Convert%2A> will fill as much space as possible and return the bytes read and chars written, provided the output array allows for at least two characters. Also see the <xref:System.Text.Encoding.GetChars%2A?displayProperty=nameWithType> topic for more comments.
 
  ]]></format>
         </remarks>