Skip to content

Commit f9de159

Browse files
carlossanlopmairaw
carlossanlop
and
mairaw
authored
Document System.IO.MemoryStream (#3532)
* Document System.IO.MemoryStream * suggestions by gewarren Co-Authored-By: Genevieve Warren <[email protected]> * Apply suggestions from code review Co-Authored-By: Maira Wenzel <[email protected]>
1 parent 197e6b6 commit f9de159

File tree

1 file changed

+103
-39
lines changed

1 file changed

+103
-39
lines changed

‎xml/System.IO/MemoryStream.xml

Lines changed: 103 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -544,14 +544,26 @@
544544
<Parameter Name="state" Type="System.Object" Index="4" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
545545
</Parameters>
546546
<Docs>
547-
<param name="buffer">To be added.</param>
548-
<param name="offset">To be added.</param>
549-
<param name="count">To be added.</param>
550-
<param name="callback">To be added.</param>
551-
<param name="state">To be added.</param>
552-
<summary>To be added.</summary>
553-
<returns>To be added.</returns>
554-
<remarks>To be added.</remarks>
547+
<param name="buffer">The buffer to read the data into.</param>
548+
<param name="offset">The byte offset in <paramref name="buffer" /> at which to begin writing data read from the memory stream.</param>
549+
<param name="count">The maximum number of bytes to read.</param>
550+
<param name="callback">An optional asynchronous callback, to be called when the read is complete.</param>
551+
<param name="state">A user-provided object that distinguishes this particular asynchronous read request from other requests.</param>
552+
<summary>Begins an asynchronous read operation. (Consider using <see cref="M:System.IO.MemoryStream.ReadAsync(System.Byte[],System.Int32,System.Int32,System.Threading.CancellationToken)" /> instead.)</summary>
553+
<returns>An <see cref="T:System.IAsyncResult" /> that represents the asynchronous read, which could still be pending.</returns>
554+
<remarks>
555+
<format type="text/markdown"><![CDATA[
556+
557+
## Remarks
558+
559+
Refer to the <xref:System.IO.Stream.BeginRead%2A> remarks for additional usage information for this method.
560+
561+
]]></format>
562+
</remarks>
563+
<exception cref="T:System.IO.IOException">Attempted an asynchronous read past the end of the memory stream, or a disk error occurred.</exception>
564+
<exception cref="T:System.ArgumentException">One or more of the arguments is invalid.</exception>
565+
<exception cref="T:System.ObjectDisposedException">Methods were called after the memory stream was closed.</exception>
566+
<exception cref="T:System.NotSupportedException">The current memory stream implementation does not support the read operation.</exception>
555567
</Docs>
556568
</Member>
557569
<Member MemberName="BeginWrite">
@@ -588,14 +600,26 @@
588600
<Parameter Name="state" Type="System.Object" Index="4" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
589601
</Parameters>
590602
<Docs>
591-
<param name="buffer">To be added.</param>
592-
<param name="offset">To be added.</param>
593-
<param name="count">To be added.</param>
594-
<param name="callback">To be added.</param>
595-
<param name="state">To be added.</param>
596-
<summary>To be added.</summary>
597-
<returns>To be added.</returns>
598-
<remarks>To be added.</remarks>
603+
<param name="buffer">The buffer to write data from.</param>
604+
<param name="offset">The byte offset in <paramref name="buffer" /> from which to begin writing.</param>
605+
<param name="count">The maximum number of bytes to write.</param>
606+
<param name="callback">An optional asynchronous callback, to be called when the write is complete.</param>
607+
<param name="state">A user-provided object that distinguishes this particular asynchronous write request from other requests.</param>
608+
<summary>Begins an asynchronous write operation. (Consider using <see cref="M:System.IO.MemoryStream.WriteAsync(System.Byte[],System.Int32,System.Int32,System.Threading.CancellationToken)" /> instead.)</summary>
609+
<returns>An <see langword="IAsyncResult" /> that represents the asynchronous write, which could still be pending.</returns>
610+
<remarks>
611+
<format type="text/markdown"><![CDATA[
612+
613+
## Remarks
614+
615+
Refer to the <xref:System.IO.Stream.BeginWrite%2A> remarks for additional usage information for this method.
616+
617+
]]></format>
618+
</remarks>
619+
<exception cref="T:System.IO.IOException">Attempted an asynchronous write past the end of the memory stream, or a disk error occurred.</exception>
620+
<exception cref="T:System.ArgumentException">One or more of the arguments is invalid.</exception>
621+
<exception cref="T:System.ObjectDisposedException">Methods were called after the memory stream was closed.</exception>
622+
<exception cref="T:System.NotSupportedException">The current memory stream implementation does not support the write operation.</exception>
599623
</Docs>
600624
</Member>
601625
<Member MemberName="CanRead">
@@ -911,10 +935,18 @@ End Try
911935
<Parameter Name="bufferSize" Type="System.Int32" Index="1" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
912936
</Parameters>
913937
<Docs>
914-
<param name="destination">To be added.</param>
915-
<param name="bufferSize">To be added.</param>
916-
<summary>To be added.</summary>
938+
<param name="destination">The stream to which the contents of the current memory stream will be copied.</param>
939+
<param name="bufferSize">The size of the buffer. This value must be greater than zero. The default size is 81920.</param>
940+
<summary>Reads the bytes from the current memory stream and writes them to another stream, using a specified buffer size.</summary>
917941
<remarks>To be added.</remarks>
942+
<exception cref="T:System.ArgumentNullException"><paramref name="destination" /> is <see langword="null" />.</exception>
943+
<exception cref="T:System.ArgumentOutOfRangeException"><paramref name="bufferSize" /> is not a positive number.</exception>
944+
<exception cref="T:System.ObjectDisposedException">Either the underlying memory stream or the <paramref name="destination" /> stream is closed.</exception>
945+
<exception cref="T:System.NotSupportedException">The underlying memory stream is unreadable.
946+
947+
-or-
948+
949+
The <paramref name="destination" /> stream is unwritable.</exception>
918950
</Docs>
919951
</Member>
920952
<Member MemberName="CopyToAsync">
@@ -1055,10 +1087,26 @@ End Try
10551087
<Parameter Name="asyncResult" Type="System.IAsyncResult" Index="0" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
10561088
</Parameters>
10571089
<Docs>
1058-
<param name="asyncResult">To be added.</param>
1059-
<summary>To be added.</summary>
1060-
<returns>To be added.</returns>
1061-
<remarks>To be added.</remarks>
1090+
<param name="asyncResult">The reference to the pending asynchronous request to finish.</param>
1091+
<summary>Waits for the pending asynchronous read to complete. (Consider using <see cref="M:System.IO.MemoryStream.ReadAsync(System.Byte[],System.Int32,System.Int32,System.Threading.CancellationToken)" /> instead.)</summary>
1092+
<returns>The number of bytes read from the memory stream, between zero (0) and the number of bytes you requested. Returns zero (0) only at the end of the memory stream, otherwise, it should block until at least one byte is available.</returns>
1093+
<remarks>
1094+
<format type="text/markdown"><![CDATA[
1095+
1096+
## Remarks
1097+
1098+
Refer to the <xref:System.IO.Stream.EndRead%2A> remarks for additional usage information for this method.
1099+
1100+
]]></format>
1101+
</remarks>
1102+
<exception cref="T:System.ArgumentNullException"><paramref name="asyncResult" /> is <see langword="null" />.</exception>
1103+
<exception cref="T:System.ArgumentException">A handle to the pending read operation is not available.
1104+
1105+
-or-
1106+
1107+
The pending operation does not support reading.</exception>
1108+
<exception cref="T:System.InvalidOperationException"><paramref name="asyncResult" /> did not originate from a <see cref="M:System.IO.MemoryStream.BeginRead(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object)" /> method on the current memory stream.</exception>
1109+
<exception cref="T:System.IO.IOException">The stream is closed or an internal error has occurred.</exception>
10621110
</Docs>
10631111
</Member>
10641112
<Member MemberName="EndWrite">
@@ -1091,9 +1139,25 @@ End Try
10911139
<Parameter Name="asyncResult" Type="System.IAsyncResult" Index="0" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
10921140
</Parameters>
10931141
<Docs>
1094-
<param name="asyncResult">To be added.</param>
1095-
<summary>To be added.</summary>
1096-
<remarks>To be added.</remarks>
1142+
<param name="asyncResult">A reference to the outstanding asynchronous I/O request.</param>
1143+
<summary>Ends an asynchronous write operation. (Consider using <see cref="M:System.IO.MemoryStream.WriteAsync(System.Byte[],System.Int32,System.Int32,System.Threading.CancellationToken)" /> instead.)</summary>
1144+
<remarks>
1145+
<format type="text/markdown"><![CDATA[
1146+
1147+
## Remarks
1148+
1149+
Refer to the <xref:System.IO.Stream.EndWrite%2A> remarks for additional usage information for this method.
1150+
1151+
]]></format>
1152+
</remarks>
1153+
<exception cref="T:System.ArgumentNullException"><paramref name="asyncResult" /> is <see langword="null" />.</exception>
1154+
<exception cref="T:System.ArgumentException">A handle to the pending write operation is not available.
1155+
1156+
-or-
1157+
1158+
The pending operation does not support writing.</exception>
1159+
<exception cref="T:System.InvalidOperationException"><paramref name="asyncResult" /> did not originate from a <see cref="M:System.IO.Stream.BeginWrite(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object)" /> method on the current stream.</exception>
1160+
<exception cref="T:System.IO.IOException">The stream is closed or an internal error has occurred.</exception>
10971161
</Docs>
10981162
</Member>
10991163
<Member MemberName="Flush">
@@ -1449,9 +1513,9 @@ End Try
14491513
<Parameter Name="destination" Type="System.Span&lt;System.Byte&gt;" Index="0" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
14501514
</Parameters>
14511515
<Docs>
1452-
<param name="destination">To be added.</param>
1453-
<summary>To be added.</summary>
1454-
<returns>To be added.</returns>
1516+
<param name="destination">A region of memory. When this method returns, the contents of this span are replaced by the bytes read from the current memory stream source.</param>
1517+
<summary>Reads a sequence of bytes from the current memory stream and advances the position within the memory stream by the number of bytes read.</summary>
1518+
<returns>The total number of bytes read into the buffer. This can be less than the number of bytes allocated in the buffer if that many bytes are not currently available, or zero (0) if the end of the memory stream has been reached.</returns>
14551519
<remarks>To be added.</remarks>
14561520
</Docs>
14571521
</Member>
@@ -1574,10 +1638,10 @@ End Try
15741638
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
15751639
</Parameters>
15761640
<Docs>
1577-
<param name="destination">To be added.</param>
1578-
<param name="cancellationToken">To be added.</param>
1579-
<summary>To be added.</summary>
1580-
<returns>To be added.</returns>
1641+
<param name="destination">The region of memory to write the data into.</param>
1642+
<param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" />.</param>
1643+
<summary>Asynchronously reads a sequence of bytes from the current memory stream, writes the sequence into <paramref name="destination" />, advances the position within the memory stream by the number of bytes read, and monitors cancellation requests.</summary>
1644+
<returns>A task that represents the asynchronous read operation. The value of its <see cref="P:System.Threading.Tasks.ValueTask`1.Result" /> property contains the total number of bytes read into the <paramref name="destination" />. The result value can be less than the number of bytes allocated in <paramref name="destination" /> if that many bytes are not currently available, or it can be 0 (zero) if the end of the memory stream has been reached.</returns>
15811645
<remarks>To be added.</remarks>
15821646
</Docs>
15831647
</Member>
@@ -1988,8 +2052,8 @@ End Try
19882052
<Parameter Name="source" Type="System.ReadOnlySpan&lt;System.Byte&gt;" Index="0" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
19892053
</Parameters>
19902054
<Docs>
1991-
<param name="source">To be added.</param>
1992-
<summary>To be added.</summary>
2055+
<param name="source">A region of memory. This method copies the contents of this region to the current memory stream.</param>
2056+
<summary>Writes the sequence of bytes contained in <paramref name="source" /> into the current memory stream and advances the current position within this memory stream by the number of bytes written.</summary>
19932057
<remarks>To be added.</remarks>
19942058
</Docs>
19952059
</Member>
@@ -2109,10 +2173,10 @@ End Try
21092173
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
21102174
</Parameters>
21112175
<Docs>
2112-
<param name="source">To be added.</param>
2113-
<param name="cancellationToken">To be added.</param>
2114-
<summary>To be added.</summary>
2115-
<returns>To be added.</returns>
2176+
<param name="source">The region of memory to write data from.</param>
2177+
<param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" />.</param>
2178+
<summary>Asynchronously writes the sequence of bytes contained in <paramref name="source" /> into the current memory stream, advances the current position within this memory stream by the number of bytes written, and monitors cancellation requests.</summary>
2179+
<returns>A task that represents the asynchronous write operation.</returns>
21162180
<remarks>To be added.</remarks>
21172181
</Docs>
21182182
</Member>

0 commit comments

Comments
 (0)