Automatically port System.Xml.Linq.XDocument triple slash (#3097)

* Automatically port System.Xml.Linq.XDocument triple slash

* Missing returns and xrefs

* remove bom character

* suggestions by rpetrusha, mairaw, krwq

Co-Authored-By: Ron Petrusha <[email protected]>

* suggestions by rpetrusha

* missed </remarks>

Author: carlossanlop

xml/System.Xml.Linq/XDocument.xml

@@ -1654,12 +1654,20 @@ Root                1    2
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="2" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
       </Parameters>
       <Docs>
-        <param name="stream">To be added.</param>
-        <param name="options">To be added.</param>
-        <param name="cancellationToken">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="stream">A stream containing the raw XML to read into the newly created <see cref="T:System.Xml.Linq.XDocument" />.</param>
+        <param name="options">A set of load options.</param>
+        <param name="cancellationToken">A cancellation token.</param>
+        <summary>Asynchronously creates a new <see cref="T:System.Xml.Linq.XDocument" /> and initializes its underlying XML tree from the specified stream, optionally preserving white space.</summary>
+        <returns>A new XDocument containing the contents of the specified <see cref="T:System.IO.Stream" />.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+If <xref:System.Xml.Linq.LoadOptions.PreserveWhitespace?displayProperty=nameWithType> is set, the underlying <xref:System.Xml.XmlReaderSettings.IgnoreWhitespace?displayProperty=nameWithType> property is set to `false`.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="LoadAsync">
@@ -1690,12 +1698,20 @@ Root                1    2
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="2" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
       </Parameters>
       <Docs>
-        <param name="textReader">To be added.</param>
-        <param name="options">To be added.</param>
-        <param name="cancellationToken">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="textReader">A reader that contains the raw XML to read into the newly created <see cref="T:System.Xml.Linq.XDocument" />.</param>
+        <param name="options">A set of load options.</param>
+        <param name="cancellationToken">A cancellation token.</param>
+        <summary>Creates a new <see cref="T:System.Xml.Linq.XDocument" /> and initializes its underlying XML tree using the specified <see cref="T:System.IO.TextReader" /> parameter, optionally preserving white space.</summary>
+        <returns>A new XDocument containing the contents of the specified <see cref="T:System.IO.TextReader" />.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+If <xref:System.Xml.Linq.LoadOptions.PreserveWhitespace?displayProperty=nameWithType> is set, the <xref:System.Xml.XmlReaderSettings.IgnoreWhitespace?displayProperty=nameWithType> property is set to `false`.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="LoadAsync">
@@ -1726,11 +1742,11 @@ Root                1    2
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="2" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
       </Parameters>
       <Docs>
-        <param name="reader">To be added.</param>
-        <param name="options">To be added.</param>
-        <param name="cancellationToken">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="reader">A reader containing the XML to be read into the new <see cref="T:System.Xml.Linq.XDocument" />.</param>
+        <param name="options">A set of load options.</param>
+        <param name="cancellationToken">A cancellation token.</param>
+        <summary>Creates a new <see cref="T:System.Xml.Linq.XDocument" /> containing the contents of the specified <see cref="T:System.Xml.XmlReader" />.</summary>
+        <returns>A new XDocument containing the contents of the specified <see cref="T:System.Xml.XmlReader" />.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -2771,10 +2787,10 @@ Console.WriteLine(File.ReadAllText("Root2.xml"))
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
       </Parameters>
       <Docs>
-        <param name="writer">To be added.</param>
-        <param name="cancellationToken">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="writer">The writer to output the XML to.</param>
+        <param name="cancellationToken">A cancellation token.</param>
+        <summary>Writes this <see cref="T:System.Xml.Linq.XDocument" /> to an <see cref="T:System.Xml.XmlWriter" />.</summary>
+        <returns>A task representing the asynchronous save operation.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -2806,12 +2822,20 @@ Console.WriteLine(File.ReadAllText("Root2.xml"))
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="2" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
       </Parameters>
       <Docs>
-        <param name="stream">To be added.</param>
-        <param name="options">To be added.</param>
-        <param name="cancellationToken">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="stream">The stream to write the XML to.</param>
+        <param name="options">A set of load options.</param>
+        <param name="cancellationToken">A cancellation token.</param>
+        <summary>Output this <see cref="T:System.Xml.Linq.XDocument" /> to a <see cref="T:System.IO.Stream" />.</summary>
+        <returns>A task representing the asynchronous save operation.</returns>
+        <remarks>  
+          <format type="text/markdown"><![CDATA[  
+
+## Remarks
+
+If <xref:System.Xml.Linq.SaveOptions.DisableFormatting?displayProperty=nameWithType> is set, the output is not indented. If <xref:System.Xml.Linq.SaveOptions.OmitDuplicateNamespaces?displayProperty=nameWithType> is set, duplicate namespace declarations will be removed.
+
+         ]]></format>
+       </remarks>
       </Docs>
     </Member>
     <Member MemberName="SaveAsync">
@@ -2842,12 +2866,20 @@ Console.WriteLine(File.ReadAllText("Root2.xml"))
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="2" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
       </Parameters>
       <Docs>
-        <param name="textWriter">To be added.</param>
-        <param name="options">To be added.</param>
-        <param name="cancellationToken">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="textWriter">The text writer to output the XML to.</param>
+        <param name="options">A set of load options.</param>
+        <param name="cancellationToken">A cancellation token.</param>
+        <summary>Writes this <see cref="T:System.Xml.Linq.XDocument" /> to a <see cref="T:System.IO.TextWriter" />.</summary>
+        <returns>A task representing the asynchronous save operation.</returns>
+         <remarks>
+           <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+If <xref:System.Xml.Linq.SaveOptions.DisableFormatting?displayProperty=nameWithType> is set, the output is not indented. If <xref:System.Xml.Linq.SaveOptions.OmitDuplicateNamespaces?displayProperty=nameWithType> is set, duplicate namespace declarations will be removed.
+
+           ]]></format>
+         </remarks>
       </Docs>
     </Member>
     <Member MemberName="WriteTo">
@@ -2967,10 +2999,10 @@ Console.WriteLine(sb.ToString())
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
       </Parameters>
       <Docs>
-        <param name="writer">To be added.</param>
-        <param name="cancellationToken">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="writer">The writer to output the content of this <see cref="T:System.Xml.Linq.XDocument" />.</param>
+        <param name="cancellationToken">A cancellation token.</param>
+        <summary>Writes this XDocument's underlying XML tree to the specified <see cref="T:System.Xml.XmlWriter" />.</summary>
+        <returns>A task representing the asynchronous write operation.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>