Skip to content

Commit 2d8c3bd

Browse files
carlossanlopRon Petrusha
andcommitted
Manually document System.IO.Compression (#2782)
* Manually document System.IO.Compression * Updates to WriteAsync * suggestions by rpetrusha Co-Authored-By: Ron Petrusha <[email protected]>
1 parent d360cb4 commit 2d8c3bd

File tree

3 files changed

+475
-144
lines changed

3 files changed

+475
-144
lines changed

xml/System.IO.Compression/BrotliStream.xml

Lines changed: 132 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -367,9 +367,22 @@
367367
</ReturnValue>
368368
<Parameters />
369369
<Docs>
370-
<summary>To be added.</summary>
371-
<returns>To be added.</returns>
372-
<remarks>To be added.</remarks>
370+
<summary>Asynchronously releases the unmanaged resources used by the <see cref="T:System.IO.Compression.BrotliStream" />.</summary>
371+
<returns>A task that represents the asynchronous dispose operation.</returns>
372+
<remarks>
373+
<format type="text/markdown">
374+
<![CDATA[
375+
376+
## Remarks
377+
378+
The `DisposeAsync` method lets you perform a resource-intensive dispose operation without blocking the main thread. This performance consideration is particularly important in a [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] app or [!INCLUDE[desktop_appname](~/includes/desktop-appname-md.md)] app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#.
379+
380+
This method disposes the Brotli stream by writing any changes to the backing store and closing the stream to release resources.
381+
382+
Calling `DisposeAsync` allows the resources used by the <xref:System.IO.Compression.BrotliStream> to be reallocated for other purposes. For more information, see [Cleaning Up Unmanaged Resources](~/docs/standard/garbage-collection/unmanaged.md).
383+
384+
]]></format>
385+
</remarks>
373386
</Docs>
374387
</Member>
375388
<Member MemberName="EndRead">
@@ -481,10 +494,18 @@
481494
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="0" FrameworkAlternate="netcore-3.0" />
482495
</Parameters>
483496
<Docs>
484-
<param name="cancellationToken">To be added.</param>
485-
<summary>To be added.</summary>
486-
<returns>To be added.</returns>
487-
<remarks>To be added.</remarks>
497+
<param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" />.</param>
498+
<summary>Asynchronously clears all buffers for this Brotli stream, causes any buffered data to be written to the underlying device, and monitors cancellation requests.</summary>
499+
<returns>A task that represents the asynchronous flush operation.</returns>
500+
<remarks>
501+
<format type="text/markdown"><![CDATA[
502+
503+
## Remarks
504+
505+
If the operation is canceled before it completes, the returned task contains the <xref:System.Threading.Tasks.TaskStatus.Canceled?displayProperty=nameWithType> value for the <xref:System.Threading.Tasks.Task.Status?displayProperty=nameWithType> property.
506+
507+
]]></format>
508+
</remarks>
488509
</Docs>
489510
</Member>
490511
<Member MemberName="Length">
@@ -561,10 +582,22 @@
561582
<Parameter Name="buffer" Type="System.Span&lt;System.Byte&gt;" Index="0" FrameworkAlternate="netcore-3.0" />
562583
</Parameters>
563584
<Docs>
564-
<param name="buffer">To be added.</param>
565-
<summary>To be added.</summary>
566-
<returns>To be added.</returns>
567-
<remarks>To be added.</remarks>
585+
<param name="buffer">A region of memory. When this method returns, the contents of this region are replaced by the bytes read from the current source.</param>
586+
<summary>Reads a sequence of bytes from the current Brotli stream to a byte span and advances the position within the Brotli stream by the number of bytes read.</summary>
587+
<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 stream has been reached.</returns>
588+
<remarks>
589+
<format type="text/markdown"><![CDATA[
590+
591+
## Remarks
592+
593+
Use the <xref:System.IO.Compression.BrotliStream.CanRead%2A> property to determine whether the current instance supports reading. Use the <xref:System.IO.Compression.BrotliStream.ReadAsync%2A> method to read asynchronously from the current stream.
594+
595+
This method read a maximum of `buffer.Length` bytes from the current stream and store them in `buffer`. The current position within the Brotli stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the Brotli stream remains unchanged. This method will block until at least one byte of data can be read, in the event that no data is available. `Read` returns 0 only when there is no more data in the stream and no more is expected (such as a closed socket or end of file). The method is free to return fewer bytes than requested even if the end of the stream has not been reached.
596+
597+
Use <xref:System.IO.BinaryReader> for reading primitive data types.
598+
599+
]]></format>
600+
</remarks>
568601
</Docs>
569602
</Member>
570603
<Member MemberName="Read">
@@ -629,11 +662,23 @@
629662
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="netcore-3.0" />
630663
</Parameters>
631664
<Docs>
632-
<param name="buffer">To be added.</param>
633-
<param name="cancellationToken">To be added.</param>
634-
<summary>To be added.</summary>
635-
<returns>To be added.</returns>
636-
<remarks>To be added.</remarks>
665+
<param name="buffer">The region of memory to write the data into.</param>
666+
<param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" />.</param>
667+
<summary>Asynchronously reads a sequence of bytes from the current Brotli stream, writes them to a byte memory range, advances the position within the Brotli stream by the number of bytes read, and monitors cancellation requests.</summary>
668+
<returns>A task that represents the asynchronous read operation, which wraps the total number of bytes read into the buffer. The result value can be less than the number of bytes allocated in the buffer if that many bytes are not currently available, or it can be 0 (zero) if the end of the Brotli stream has been reached.</returns>
669+
<remarks>
670+
<format type="text/markdown"><![CDATA[
671+
672+
## Remarks
673+
674+
The `ReadAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] app or [!INCLUDE[desktop_appname](~/includes/desktop-appname-md.md)] app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#.
675+
676+
Use the <xref:System.IO.Compression.BrotliStream.CanRead%2A> property to determine whether the current instance supports reading.
677+
678+
If the operation is canceled before it completes, the returned task contains the <xref:System.Threading.Tasks.TaskStatus.Canceled?displayProperty=nameWithType> value for the <xref:System.Threading.Tasks.Task.Status?displayProperty=nameWithType> property.
679+
680+
]]></format>
681+
</remarks>
637682
</Docs>
638683
</Member>
639684
<Member MemberName="ReadAsync">
@@ -661,13 +706,25 @@
661706
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" />
662707
</Parameters>
663708
<Docs>
664-
<param name="buffer">To be added.</param>
665-
<param name="offset">To be added.</param>
666-
<param name="count">To be added.</param>
667-
<param name="cancellationToken">To be added.</param>
668-
<summary>To be added.</summary>
669-
<returns>To be added.</returns>
670-
<remarks>To be added.</remarks>
709+
<param name="buffer">The buffer to write the data into.</param>
710+
<param name="offset">The byte offset in <paramref name="buffer" /> at which to begin writing data from the Brotli stream.</param>
711+
<param name="count">The maximum number of bytes to read.</param>
712+
<param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" />.</param>
713+
<summary>Asynchronously reads a sequence of bytes from the current Brotli stream, writes them to a byte array starting at a specified index, advances the position within the Brotli stream by the number of bytes read, and monitors cancellation requests.</summary>
714+
<returns>A task that represents the asynchronous read operation, which wraps the total number of bytes read into the <paramref name="buffer" />. The result value can be less than the number of bytes requested if the number of bytes currently available is less than the requested number, or it can be 0 (zero) if the end of the Brotli stream has been reached.</returns>
715+
<remarks>
716+
<format type="text/markdown"><![CDATA[
717+
718+
## Remarks
719+
720+
The `ReadAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] app or [!INCLUDE[desktop_appname](~/includes/desktop-appname-md.md)] app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#.
721+
722+
Use the <xref:System.IO.Compression.BrotliStream.CanRead%2A> property to determine whether the current instance supports reading.
723+
724+
If the operation is canceled before it completes, the returned task contains the <xref:System.Threading.Tasks.TaskStatus.Canceled?displayProperty=nameWithType> value for the <xref:System.Threading.Tasks.Task.Status?displayProperty=nameWithType> property.
725+
726+
]]></format>
727+
</remarks>
671728
</Docs>
672729
</Member>
673730
<Member MemberName="Seek">
@@ -752,9 +809,21 @@
752809
<Parameter Name="buffer" Type="System.ReadOnlySpan&lt;System.Byte&gt;" Index="0" FrameworkAlternate="netcore-3.0" />
753810
</Parameters>
754811
<Docs>
755-
<param name="buffer">To be added.</param>
756-
<summary>To be added.</summary>
757-
<remarks>To be added.</remarks>
812+
<param name="buffer">A region of memory. This method copies the contents of this region to the current Brotli stream.</param>
813+
<summary>Writes a sequence of bytes to the current Brotli stream from a read-only byte span and advances the current position within this Brotli stream by the number of bytes written.</summary>
814+
<remarks>
815+
<format type="text/markdown">
816+
<![CDATA[
817+
818+
## Remarks
819+
820+
Use the <xref:System.IO.Compression.BrotliStream.CanWrite%2A> property to determine whether the current instance supports writing. Use the <xref:System.IO.Compression.BrotliStream.WriteAsync%2A> method to write asynchronously to the current stream.
821+
822+
If the write operation is successful, the position within the Brotli stream advances by the number of bytes written. If an exception occurs, the position within the Brotli stream remains unchanged.
823+
824+
]]>
825+
</format>
826+
</remarks>
758827
</Docs>
759828
</Member>
760829
<Member MemberName="Write">
@@ -811,11 +880,23 @@
811880
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="netcore-3.0" />
812881
</Parameters>
813882
<Docs>
814-
<param name="buffer">To be added.</param>
815-
<param name="cancellationToken">To be added.</param>
816-
<summary>To be added.</summary>
817-
<returns>To be added.</returns>
818-
<remarks>To be added.</remarks>
883+
<param name="buffer">The memory region to write data from.</param>
884+
<param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" />.</param>
885+
<summary>Asynchronously writes compressed bytes to the underlying Brotli stream from the specified byte memory range.</summary>
886+
<returns>A task that represents the asynchronous write operation.</returns>
887+
<remarks>
888+
<format type="text/markdown"><![CDATA[
889+
890+
## Remarks
891+
892+
The `WriteAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] app or [!INCLUDE[desktop_appname](~/includes/desktop-appname-md.md)] app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#.
893+
894+
Use the <xref:System.IO.Compression.BrotliStream.CanWrite%2A> property to determine whether the current instance supports writing.
895+
896+
If the operation is canceled before it completes, the returned task contains the <xref:System.Threading.Tasks.TaskStatus.Canceled?displayProperty=nameWithType> value for the <xref:System.Threading.Tasks.Task.Status?displayProperty=nameWithType> property.
897+
898+
]]></format>
899+
</remarks>
819900
</Docs>
820901
</Member>
821902
<Member MemberName="WriteAsync">
@@ -843,14 +924,26 @@
843924
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" />
844925
</Parameters>
845926
<Docs>
846-
<param name="buffer">To be added.</param>
847-
<param name="offset">To be added.</param>
848-
<param name="count">To be added.</param>
849-
<param name="cancellationToken">To be added.</param>
850-
<summary>To be added.</summary>
851-
<returns>To be added.</returns>
852-
<remarks>To be added.</remarks>
927+
<param name="buffer">The buffer that contains the data to compress.</param>
928+
<param name="offset">The zero-based byte offset in <paramref name="buffer" /> from which to begin copying bytes to the Brotli stream.</param>
929+
<param name="count">The maximum number of bytes to write.</param>
930+
<param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" />.</param>
931+
<summary>Asynchronously writes compressed bytes to the underlying Brotli stream from the specified byte array.</summary>
932+
<returns>A task that represents the asynchronous write operation.</returns>
933+
<remarks>
934+
<format type="text/markdown"><![CDATA[
935+
936+
## Remarks
937+
938+
The `WriteAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] app or [!INCLUDE[desktop_appname](~/includes/desktop-appname-md.md)] app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#.
939+
940+
Use the <xref:System.IO.Compression.BrotliStream.CanWrite%2A> property to determine whether the current instance supports writing.
941+
942+
If the operation is canceled before it completes, the returned task contains the <xref:System.Threading.Tasks.TaskStatus.Canceled?displayProperty=nameWithType> value for the <xref:System.Threading.Tasks.Task.Status?displayProperty=nameWithType> property.
943+
944+
]]></format>
945+
</remarks>
853946
</Docs>
854947
</Member>
855948
</Members>
856-
</Type>
949+
</Type>

0 commit comments

Comments
 (0)