Manually comment System.IO.IsolatedStorage.IsolatedStorageFileStream (#2764)

carlossanlop · Ron Petrusha · commit 7cd16e23841b · 2019-07-22T16:58:16.000Z
* Manually comment System.IO.IsolatedStorage.IsolatedStorageFileStream

* suggestions by rpetrusha

Co-Authored-By: Ron Petrusha &lt;ronpet@microsoft.com&gt;

* Write/WriteAsync disambiguation
diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorageFileStream.xml b/xml/System.IO.IsolatedStorage/IsolatedStorageFileStream.xml
@@ -999,8 +999,8 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile)
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <summary>Asynchronously releases the unmanaged resources used by the <see cref="T:System.IO.IsolatedStorage.IsolatedStorageFileStream" />.</summary>
+        <returns>A task that represents the asynchronous dispose operation.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -1221,9 +1221,9 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile)
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="0" FrameworkAlternate="dotnet-uwp-10.0;netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="cancellationToken">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" />.</param>
+        <summary>Asynchronously clears buffers for this stream and causes any buffered data to be written to the file.</summary>
+        <returns>A task that represents the asynchronous flush operation.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -1521,9 +1521,9 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile)
         <Parameter Name="buffer" Type="System.Span&lt;System.Byte&gt;" Index="0" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="buffer">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="buffer">The buffer to write the data into.</param>
+        <summary>Copies bytes from the current buffered <see cref="T:System.IO.IsolatedStorage.IsolatedStorageFileStream" /> object to a byte span.</summary>
+        <returns>The total number of bytes read into the <paramref name="buffer" />. This can be less than the number of bytes requested if that many bytes are not currently available, or zero if the end of the stream is reached.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -1562,22 +1562,25 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile)
         <Parameter Name="count" Type="System.Int32" />
       </Parameters>
       <Docs>
-        <param name="buffer">The buffer to read.</param>
+        <param name="buffer">The buffer to write the data into.</param>
         <param name="offset">The offset in the buffer at which to begin writing.</param>
         <param name="count">The maximum number of bytes to read.</param>
-        <summary>Copies bytes from the current buffered <see cref="T:System.IO.IsolatedStorage.IsolatedStorageFileStream" /> object to an array.</summary>
+        <summary>Copies bytes from the current buffered <see cref="T:System.IO.IsolatedStorage.IsolatedStorageFileStream" /> object to a byte array.</summary>
         <returns>The total number of bytes read into the <paramref name="buffer" />. This can be less than the number of bytes requested if that many bytes are not currently available, or zero if the end of the stream is reached.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- The `buffer` parameter can be an instance of the <xref:System.Buffer> class, or an array of one of the following types: <xref:System.Byte>, <xref:System.SByte>, <xref:System.Char>, <xref:System.Int16>, <xref:System.Int32>, <xref:System.Int64>, <xref:System.UInt16>, <xref:System.UInt32>, <xref:System.UInt64>, <xref:System.Single>, or <xref:System.Double>. The `offset` parameter gives the offset of the byte in buffer at which to begin writing (index in the buffer), and the `count` parameter gives the maximum number of bytes that will be read from this stream. The returned value is the actual number of bytes read, or zero if the end of the stream is reached. If the read operation is successful, the current position of the stream is advanced by the number of bytes read. If an exception occurs, the current position of the stream is unchanged.  
-  
- The <xref:System.IO.IsolatedStorage.IsolatedStorageFileStream.Read%2A> method treats the `buffer` parameter as a block of bytes, regardless of its actual type. Likewise, the `offset` and `count` parameters are always specified in bytes. For `buffer` parameters other than byte arrays, this means that an element index must be multiplied by the element size in bytes to form a correct value for `offset` or `count`.  
-  
- The <xref:System.IO.IsolatedStorage.IsolatedStorageFileStream.Read%2A> method will return zero only if the end of the stream is reached. In all other cases, <xref:System.IO.IsolatedStorage.IsolatedStorageFileStream.Read%2A> always reads at least one byte from the stream before returning. If no data is available from the <xref:System.IO.IsolatedStorage.IsolatedStorageFileStream> object upon a call to <xref:System.IO.IsolatedStorage.IsolatedStorageFileStream.Read%2A>, the method will block until at least one byte of data can be returned.  
-  
- ]]></format>
+
+## Remarks
+
+The `buffer` parameter can be an instance of the <xref:System.Buffer> class, or an array of one of the following types: <xref:System.Byte>, <xref:System.SByte>, <xref:System.Char>, <xref:System.Int16>, <xref:System.Int32>, <xref:System.Int64>, <xref:System.UInt16>, <xref:System.UInt32>, <xref:System.UInt64>, <xref:System.Single>, or <xref:System.Double>. 
+
+If the read operation is successful, the current position of the stream is advanced by the number of bytes read. If an exception occurs, the current position of the stream is unchanged.
+
+The <xref:System.IO.IsolatedStorage.IsolatedStorageFileStream.Read%2A> method treats the `buffer` parameter as a block of bytes, regardless of its actual type. Likewise, the `offset` and `count` parameters are always specified in bytes. For `buffer` parameters other than byte arrays, this means that an element index or the number of elements must be multiplied by the element size in bytes to form a correct value for `offset` or `count`.
+
+The <xref:System.IO.IsolatedStorage.IsolatedStorageFileStream.Read%2A> method will return zero only if the end of the stream is reached. In all other cases, <xref:System.IO.IsolatedStorage.IsolatedStorageFileStream.Read%2A> always reads at least one byte from the stream before returning. If no data is available from the <xref:System.IO.IsolatedStorage.IsolatedStorageFileStream> object upon a call to <xref:System.IO.IsolatedStorage.IsolatedStorageFileStream.Read%2A>, the method will block until at least one byte of data can be returned.
+
+          ]]></format>
         </remarks>
       </Docs>
     </Member>
@@ -1605,10 +1608,10 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile)
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="buffer">To be added.</param>
-        <param name="cancellationToken">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="buffer">The buffer to write the data into.</param>
+        <param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" />.</param>
+        <summary>Asynchronously copies bytes from the current buffered <see cref="T:System.IO.IsolatedStorage.IsolatedStorageFileStream" /> object to a byte memory range.</summary>
+        <returns>A task that represents the asynchronous read operation. It wraps the total number of bytes read into the <paramref name="buffer" />. This can be less than the number of bytes requested if that many bytes are not currently available, or zero if the end of the stream is reached.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -1640,13 +1643,27 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile)
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="3" FrameworkAlternate="dotnet-uwp-10.0;netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="buffer">To be added.</param>
-        <param name="offset">To be added.</param>
-        <param name="count">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="buffer">The buffer to write the data into.</param>
+        <param name="offset">The offset in the buffer at which to begin writing.</param>
+        <param name="count">The maximum number of bytes to read.</param>
+        <param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" />.</param>
+        <summary>Asynchronously copies bytes from the current buffered <see cref="T:System.IO.IsolatedStorage.IsolatedStorageFileStream" /> object to a byte array.</summary>
+        <returns>A task that represents the asynchronous read operation. It wraps the total number of bytes read into the <paramref name="buffer" />. This can be less than the number of bytes requested if that many bytes are not currently available, or zero if the end of the stream is reached.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+
+## Remarks
+
+The `buffer` parameter can be an instance of the <xref:System.Buffer> class, or an array of one of the following types: <xref:System.Byte>, <xref:System.SByte>, <xref:System.Char>, <xref:System.Int16>, <xref:System.Int32>, <xref:System.Int64>, <xref:System.UInt16>, <xref:System.UInt32>, <xref:System.UInt64>, <xref:System.Single>, or <xref:System.Double>. 
+
+If the read operation is successful, the current position of the stream is advanced by the number of bytes read. If an exception occurs, the current position of the stream is unchanged.
+
+The <xref:System.IO.IsolatedStorage.IsolatedStorageFileStream.ReadAsync%2A> method treats the `buffer` parameter as a block of bytes, regardless of its actual type. Likewise, the `offset` and `count` parameters are always specified in bytes. For `buffer` parameters other than byte arrays, this means that an element index or the number of elements must be multiplied by the element size in bytes to form a correct value for `offset` or `count`.
+
+The <xref:System.IO.IsolatedStorage.IsolatedStorageFileStream.ReadAsync%2A> method will return zero only if the end of the stream is reached. In all other cases, <xref:System.IO.IsolatedStorage.IsolatedStorageFileStream.ReadAsync%2A> always reads at least one byte from the stream before returning. If no data is available from the <xref:System.IO.IsolatedStorage.IsolatedStorageFileStream> object upon a call to <xref:System.IO.IsolatedStorage.IsolatedStorageFileStream.ReadAsync%2A>, the method will block until at least one byte of data can be returned.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="ReadByte">
@@ -1913,8 +1930,8 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile)
         <Parameter Name="buffer" Type="System.ReadOnlySpan&lt;System.Byte&gt;" Index="0" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="buffer">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="buffer">The read-only byte span from which to copy bytes to the current isolated storage file stream.</param>
+        <summary>Writes a block of bytes to the isolated storage file stream object using data read from a buffer consisting of a read-only byte span.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -1958,17 +1975,18 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile)
         <Parameter Name="count" Type="System.Int32" />
       </Parameters>
       <Docs>
-        <param name="buffer">The buffer to write.</param>
-        <param name="offset">The byte offset in buffer from which to begin.</param>
+        <param name="buffer">The byte array from which to copy bytes to the current isolated storage file stream.</param>
+        <param name="offset">The byte offset in <paramref name="buffer" /> from which to begin.</param>
         <param name="count">The maximum number of bytes to write.</param>
-        <summary>Writes a block of bytes to the <see cref="T:System.IO.IsolatedStorage.IsolatedStorageFileStream" /> object using data read from a byte array.</summary>
+        <summary>Writes a block of bytes to the isolated storage file stream object using data read from a buffer consisting of a byte array.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- The `offset` parameter gives the offset of the byte in the `buffer` at which to begin reading, and the `count` parameter gives the number of bytes that will be written to this <xref:System.IO.IsolatedStorage.IsolatedStorageFileStream> object. If the write operation is successful, the current position of the <xref:System.IO.IsolatedStorage.IsolatedStorageFileStream> object is advanced by the number of bytes written. If an exception occurs, the current position of the <xref:System.IO.IsolatedStorage.IsolatedStorageFileStream> object is unchanged.  
-  
- ]]></format>
+
+## Remarks
+
+If the write operation is successful, the current position of the <xref:System.IO.IsolatedStorage.IsolatedStorageFileStream> object is advanced by the number of bytes written. If an exception occurs, the current position of the <xref:System.IO.IsolatedStorage.IsolatedStorageFileStream> object is unchanged.  
+
+          ]]></format>
         </remarks>
         <exception cref="T:System.IO.IsolatedStorage.IsolatedStorageException">The write attempt exceeds the quota for the <see cref="T:System.IO.IsolatedStorage.IsolatedStorageFileStream" /> object.</exception>
       </Docs>
@@ -1997,10 +2015,10 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile)
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="buffer">To be added.</param>
-        <param name="cancellationToken">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="buffer">The read-only byte memory from which to copy bytes to the current isolated storage file stream.</param>
+        <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 block of bytes to the isolated storage file stream object using data read from a buffer consisting of a read-only byte memory range.</summary>
+        <returns>A task that represents the asynchronous write operation.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -2032,13 +2050,21 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile)
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="3" FrameworkAlternate="dotnet-uwp-10.0;netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="buffer">To be added.</param>
-        <param name="offset">To be added.</param>
-        <param name="count">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="buffer">The byte array from which to copy bytes to the current isolated storage file stream.</param>
+        <param name="offset">The byte offset in <paramref name="buffer" /> from which to begin.</param>
+        <param name="count">The maximum number of bytes to write.</param>
+        <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 block of bytes to the isolated storage file stream object using data read from a buffer consisting of a byte array.</summary>
+        <returns>A task that represents the asynchronous write operation.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks
+
+If the write operation is successful, the current position of the <xref:System.IO.IsolatedStorage.IsolatedStorageFileStream> object is advanced by the number of bytes written. If an exception occurs, the current position of the <xref:System.IO.IsolatedStorage.IsolatedStorageFileStream> object is unchanged.  
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="WriteByte">
@@ -2097,4 +2123,4 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile)
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>
