coreclr: Automatic port of triple slash from System.IO (#2724)

* coreclr: Automatic port of triple slash from System.IO

* Suggestions by mairaw

Co-Authored-By: Maira Wenzel <[email protected]>

* missing returns in EndsInDirectorySeparator

* Update for GetDirectoryName

* mairaw's commits

* Additional merge conflicts

* spacing

* spacing

* Update Path.xml

Author: carlossanlop

xml/System.IO/Path.xml

@@ -647,9 +647,9 @@ The following example displays <xref:System.IO.Path> field values on Windows and
         <Parameter Name="path" Type="System.ReadOnlySpan&lt;System.Char&gt;" Index="0" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="path">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="path">The path to analyze.</param>
+        <summary>Returns a value that indicates whether the path, specified as a read-only span, ends in a directory separator.</summary>
+        <returns><see langword="true" /> if the path ends in a directory separator; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -678,9 +678,9 @@ The following example displays <xref:System.IO.Path> field values on Windows and
         <Parameter Name="path" Type="System.String" Index="0" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="path">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="path">The path to analyze.</param>
+        <summary>Returns a value that indicates whether the specified path ends in a directory separator.</summary>
+        <returns><see langword="true" /> if the path ends in a directory separator; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -710,10 +710,18 @@ The following example displays <xref:System.IO.Path> field values on Windows and
         <Parameter Name="path" Type="System.ReadOnlySpan&lt;System.Char&gt;" Index="0" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
       </Parameters>
       <Docs>
-        <param name="path">To be added.</param>
+        <param name="path">The path to retrieve the directory information from.</param>
         <summary>Returns the directory information for the specified path represented by a character span.</summary>
         <returns>Directory information for <paramref name="path" />, or an empty span if <paramref name="path" /> is <see langword="null" />, an empty span, or a root (such as \, C:, or \\server\share).</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Unlike the string overload, this method doesn't normalize directory separators.
+
+          ]]></format>
+        </remarks>
         <related type="Article" href="~/docs/standard/io/file-path-formats.md">File path formats on Windows systems</related>
       </Docs>
     </Member>
@@ -1393,7 +1401,15 @@ The following example defines a variable, `basePath`, to represent an applicatio
         <param name="path">The path from which to obtain root directory information.</param>
         <summary>Gets the root directory information from the path contained in the specified character span.</summary>
         <returns>A character span containing the root directory of `path`.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Unlike the string overload, this method doesn't normalize directory separators.
+
+          ]]></format>
+        </remarks>
         <related type="article" href="~/docs/standard/io/file-path-formats.md">File path formats on Windows systems</related>
       </Docs>
     </Member>
@@ -1983,7 +1999,15 @@ There is a difference between a fully qualified path (as indicated by the `IsPat
         <summary>Returns a value that indicates whether the specified file path is fixed to a specific drive or UNC path.</summary>
         <returns>
           <see langword="true" /> if the path is fixed to a specific drive or UNC path; <see langword="false" /> if the path is relative to the current drive or working directory.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+This method handles paths that use the alternate directory separator. It's a frequent mistake to assume that rooted paths (<xref:System.IO.Path.IsPathRooted(System.String)>) aren't relative. For example, "C:a" is drive relative, that is, it's resolved against the current directory for C: (rooted, but relative). "C:\a" is rooted and not relative, that is, the current directory isn't used to modify the path.
+
+          ]]></format>
+        </remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="path" /> is <see langword="null" />.</exception>
         <related type="article" href="~/docs/standard/io/file-path-formats.md">File path formats on Windows systems</related>
@@ -2580,8 +2604,8 @@ Not all invalid characters for directory and file names are interpreted as unacc
       </Parameters>
       <Docs>
         <param name="path">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <summary>Trims one trailing directory separator beyond the root of the specified path.</summary>
+        <returns>The <paramref name="path" /> without any trailing directory separators.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -2611,8 +2635,8 @@ Not all invalid characters for directory and file names are interpreted as unacc
       </Parameters>
       <Docs>
         <param name="path">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <summary>Trims one trailing directory separator beyond the root of the specified path.</summary>
+        <returns>The <paramref name="path" /> without any trailing directory separators.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -2785,4 +2809,4 @@ The destination character span must be large enough to hold the concatenated pat
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>

xml/System.IO/TextWriter.xml

@@ -2445,7 +2445,15 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the
         <param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" />.</param>
         <summary>Asynchronously writes a string builder to the text stream.</summary>
         <returns>A task that represents the asynchronous write operation.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks  
+
+This method is equivalent to calling `WriteAsync(stringBuilder.ToString())`, however, it uses the <xref:System.Text.StringBuilder.GetChunks?displayProperty=nameWithType> method to avoid creating the intermediate string.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="WriteAsync">

xml/System.IO/UnmanagedMemoryStream.xml

@@ -711,9 +711,7 @@
       </Parameters>
       <Docs>
         <param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" />.</param>
-        <summary>Overrides the <see cref="M:System.IO.Stream.FlushAsync(System.Threading.CancellationToken)" /> method so that the operation is cancelled if specified, but no other action is performed.  
-  
- Available starting in .NET Framework 4.6</summary>
+        <summary>Overrides the <see cref="M:System.IO.Stream.FlushAsync(System.Threading.CancellationToken)" /> method so that the operation is cancelled if specified, but no other action is performed.</summary>
         <returns>A task that represents the asynchronous flush operation.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[  
@@ -786,12 +784,13 @@
         <param name="access">One of the <see cref="T:System.IO.FileAccess" /> values.</param>
         <summary>Initializes a new instance of the <see cref="T:System.IO.UnmanagedMemoryStream" /> class by using a pointer to an unmanaged memory location.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
+          <format type="text/markdown"><![CDATA[
+
 ## Remarks  
- This method is equivalent to the <xref:System.IO.UnmanagedMemoryStream.%23ctor%2A> constructor. It supports methods that need to initialize the pointer before setting stream variables and, therefore, cannot call the parameterized constructor. Such methods should use the parameterless constructor, <xref:System.IO.UnmanagedMemoryStream.%23ctor>, initialize the pointer, and then invoke the <xref:System.IO.UnmanagedMemoryStream.Initialize%2A> method.  
-  
- ]]></format>
+
+This method is equivalent to the <xref:System.IO.UnmanagedMemoryStream.%23ctor%2A> constructor. It supports methods that need to initialize the pointer before setting stream variables and, therefore, cannot call the parameterized constructor. Such methods should use the parameterless constructor, <xref:System.IO.UnmanagedMemoryStream.%23ctor>, initialize the pointer, and then invoke the <xref:System.IO.UnmanagedMemoryStream.Initialize%2A> method.  
+
+          ]]></format>
         </remarks>
         <exception cref="T:System.Security.SecurityException">The user does not have the required permission.</exception>
         <exception cref="T:System.ArgumentNullException">The <paramref name="pointer" /> value is <see langword="null" />.</exception>
@@ -1576,7 +1575,15 @@
         <param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" />.</param>
         <summary>Asynchronously writes a span of bytes to the current stream, advances the current position within this stream by the number of bytes written, and monitors cancellation requests.</summary>
         <returns>A task that represents the asynchronous write operation.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+If an exception occurs during the write operation, it will be set as the <xref:System.Threading.Tasks.Task.Exception%2A?displayProperty=nameWithType> of the property of the returned task.
+
+            ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="WriteAsync">