From eef4d2adce0982c0ea350c84b6bad14fdeaefeec Mon Sep 17 00:00:00 2001
From: Maira Wenzel <mairaw@microsoft.com>
Date: Thu, 25 Jul 2019 11:56:23 -0700
Subject: [PATCH] style guide + missing sections

---
 xml/System.Buffers/SequenceReader`1.xml | 32 ++++++++++++++-----------
 1 file changed, 18 insertions(+), 14 deletions(-)

diff --git a/xml/System.Buffers/SequenceReader`1.xml b/xml/System.Buffers/SequenceReader`1.xml
index cda5104f27b..05cda8fee77 100644
--- a/xml/System.Buffers/SequenceReader`1.xml
+++ b/xml/System.Buffers/SequenceReader`1.xml
@@ -340,9 +340,9 @@
       </Parameters>
       <Docs>
         <param name="next">The span to compare the next items to.</param>
-        <param name="advancePast"><see langword="true" /> to move past the <paramref name="next" /> values if they are found, or <see langword="false" /> to not move past them. </param>
+        <param name="advancePast"><see langword="true" /> to move past the <paramref name="next" /> values if they are found; otherwise, <see langword="false" />. </param>
         <summary>Checks whether the values specified in a read-only span are next in the sequence.</summary>
-        <returns>To be added.</returns>
+        <returns><see langword="true" /> if the values are next in sequence; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -366,9 +366,9 @@
       </Parameters>
       <Docs>
         <param name="next">The value to compare the next items to.</param>
-        <param name="advancePast"><see langword="true" /> to move past the <paramref name="next" /> values if they are found, or <see langword="false" /> to not move past them. </param>
+        <param name="advancePast"><see langword="true" /> to move past the <paramref name="next" /> values if they are found; otherwise, <see langword="false" />.</param>
         <summary>Checks whether a specified value is next in the sequence.</summary>
-        <returns>To be added.</returns>
+        <returns><see langword="true" /> if the values are next in sequence; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -551,7 +551,7 @@
         <param name="delimiters">The delimiters to search for.</param>
         <param name="advancePastDelimiter"><see langword="true" /> to move past the first instance of any of the given <paramref name="delimiters" />; <see lanword="false" /> to not move past the delimiter.</param>
         <summary>Searches for any of a number of specified delimiters and optionally advances past the first one to be found.</summary>
-        <returns><see langword="true" /> if any of the given <paramref name="delimiters" /> was found.</returns>
+        <returns><see langword="true" /> if any of the given <paramref name="delimiters" /> was found; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -585,7 +585,11 @@
         <returns><see langword="true" /> if there is enough data to completely fill the <paramref name="destination" /> span; otherwise, <see langword="false" />.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[
+
+## Remarks
+
 This method copies a fixed amount of data out of the sequence if possible. It does not advance the reader. To look ahead for a specific stream of data, use  <xref:System.Buffers.SequenceReader`1.IsNext(System.ReadOnlySpan{`0},System.Boolean)>.
+
           ]]></format>
         </remarks>
       </Docs>
@@ -667,7 +671,7 @@ This method copies a fixed amount of data out of the sequence if possible. It do
       <Docs>
         <param name="sequence">When the method returns, contains the data read, if any.</param>
         <param name="delimiter">A read-only span that contains one or more delimiters.</param>
-        <param name="advancePastDelimiter"><see langword="true" /> to move past the <paramref name="delimiter" /> if found.</param>
+        <param name="advancePastDelimiter"><see langword="true" /> to move past the <paramref name="delimiter" /> if found; otherwise, <see langword="false" />.</param>
         <summary>Tries to read data until the entire delimiter specified as a read-only span matches.</summary>
         <returns><see langword="true" /> if the <paramref name="delimiter" /> was found; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
@@ -695,7 +699,7 @@ This method copies a fixed amount of data out of the sequence if possible. It do
       <Docs>
         <param name="sequence">When the method returns, contains the data read, if any.</param>
         <param name="delimiter">The delimiter to look for.</param>
-        <param name="advancePastDelimiter"><see langword="true" /> to move past the <paramref name="delimiter" /> if found.</param>
+        <param name="advancePastDelimiter"><see langword="true" /> to move past the <paramref name="delimiter" /> if found; otherwise, <see langword="false" />.</param>
         <summary>Tries to read everything up to the given <paramref name="delimiter" />.</summary>
         <returns><see langword="true" /> if the <paramref name="delimiter" /> was found; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
@@ -723,9 +727,9 @@ This method copies a fixed amount of data out of the sequence if possible. It do
       <Docs>
         <param name="span">When the method returns, contains the data read, if any.</param>
         <param name="delimiter">The delimiter to look for.</param>
-        <param name="advancePastDelimiter"><see langword="true" /> to move past the <paramref name="delimiter" /> if found.</param>
+        <param name="advancePastDelimiter"><see langword="true" /> to move past the <paramref name="delimiter" /> if found; otherwise, <see langword="false" />.</param>
         <summary>Tries to read everything up to the given <paramref name="delimiter" />.</summary>
-        <returns><see langword="true" /> if the <paramref name="delimiter" /> was found.</returns>
+        <returns><see langword="true" /> if the <paramref name="delimiter" /> was found; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -753,7 +757,7 @@ This method copies a fixed amount of data out of the sequence if possible. It do
         <param name="sequence">When the method returns, contains the data read, if any.</param>
         <param name="delimiter">The delimiter to look for.</param>
         <param name="delimiterEscape">A value that indicates that an immediately following <paramref name="delimiter" /> is to be skipped.</param>
-        <param name="advancePastDelimiter"><see langword="true" /> to move past the <paramref name="delimiter" /> if found.</param>
+        <param name="advancePastDelimiter"><see langword="true" /> to move past the <paramref name="delimiter" /> if found; otherwise, <see langword="false" />.</param>
         <summary>Tries to read everything up to the given <paramref name="delimiter" />, ignoring delimiters that are preceded by <paramref name="delimiterEscape" />.</summary>
         <returns><see langword="true" /> if the <paramref name="delimiter" /> was found; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
@@ -783,7 +787,7 @@ This method copies a fixed amount of data out of the sequence if possible. It do
         <param name="span">When the method returns, contains the data read, if any.</param>
         <param name="delimiter">The delimiter to look for.</param>
         <param name="delimiterEscape">A value that indicates that an immediately following <paramref name="delimiter" /> is to be skipped.</param>
-        <param name="advancePastDelimiter"><see langword="true" /> to move past the <paramref name="delimiter" /> if found.</param>
+        <param name="advancePastDelimiter"><see langword="true" /> to move past the <paramref name="delimiter" /> if found; otherwise, <see langword="false" />.</param>
         <summary>Tries to read everything up to the given <paramref name="delimiter" />, ignoring delimiters that are preceded by <paramref name="delimiterEscape" />.</summary>
         <returns><see langword="true" /> if the <paramref name="delimiter" /> was found; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
@@ -811,7 +815,7 @@ This method copies a fixed amount of data out of the sequence if possible. It do
       <Docs>
         <param name="sequence">When the method returns, contains the data read, if any.</param>
         <param name="delimiters">The delimiters to look for.</param>
-        <param name="advancePastDelimiter"><see langword="true" /> to move past the first found instance of any of the given <paramref name="delimiters" />.</param>
+        <param name="advancePastDelimiter"><see langword="true" /> to move past the first found instance of any of the given <paramref name="delimiters" />; otherwise, <see langword="false" />.</param>
         <summary>Tries to read everything up to any of the specified <paramref name="delimiters" />.</summary>
         <returns><see langword="true" /> if any of the <paramref name="delimiters" /> were found; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
@@ -839,7 +843,7 @@ This method copies a fixed amount of data out of the sequence if possible. It do
       <Docs>
         <param name="span">When the method returns, contains the data read, if any.</param>
         <param name="delimiters">The delimiters to look for.</param>
-        <param name="advancePastDelimiter"><see langword="true" /> to move past the first found instance of any of the given <paramref name="delimiters" />.</param>
+        <param name="advancePastDelimiter"><see langword="true" /> to move past the first found instance of any of the given <paramref name="delimiters" />; otherwise, <see langword="false" />.</param>
         <summary>Tries to read everything up to any of the specified <paramref name="delimiters" />.</summary>
         <returns><see langword="true" /> if any of the <paramref name="delimiters" /> were found; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
@@ -867,7 +871,7 @@ This method copies a fixed amount of data out of the sequence if possible. It do
       </ReturnValue>
       <Docs>
         <summary>Gets the unread portion of the <see cref="P:System.Buffers.SequenceReader`1.CurrentSpan" />.</summary>
-        <value>To be added.</value>
+        <value>The unread portion of the <see cref="P:System.Buffers.SequenceReader`1.CurrentSpan" />.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>