Skip to content

Commit 54957b5

Browse files
carlossanlopRon Petrusha
carlossanlop
and
Ron Petrusha
committed
Document System.IO.Compression BrotliEncoder and BrotliStream (#3298)
* Document System.IO.Compression BrotliEncoder and BrotliStream * sugestions by rpetrusha Co-Authored-By: Ron Petrusha <[email protected]>
1 parent bd2dca8 commit 54957b5

File tree

2 files changed

+49
-33
lines changed

2 files changed

+49
-33
lines changed

‎xml/System.IO.Compression/BrotliEncoder.xml

Lines changed: 48 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
</Interface>
2323
</Interfaces>
2424
<Docs>
25-
<summary>To be added.</summary>
25+
<summary>Provides methods and static methods to encode and decode data in a streamless, non-allocating, and performant manner using the Brotli data format specification.</summary>
2626
<remarks>To be added.</remarks>
2727
</Docs>
2828
<Members>
@@ -47,10 +47,17 @@
4747
<Parameter Name="window" Type="System.Int32" />
4848
</Parameters>
4949
<Docs>
50-
<param name="quality">To be added.</param>
51-
<param name="window">To be added.</param>
52-
<summary>To be added.</summary>
50+
<param name="quality">A number representing quality of the Brotli compression. 0 is the minimum (no compression), 11 is the maximum.</param>
51+
<param name="window">A number representing the encoder window bits. The minimum value is 10, and the maximum value is 24.</param>
52+
<summary>Initializes a new instance of the <see cref="T:System.IO.Compression.BrotliEncoder" /> structure using the specified quality and window.</summary>
5353
<remarks>To be added.</remarks>
54+
<exception cref="T:System.ArgumentOutOfRangeException"><paramref name="quality" /> is not between the minimum value of 0 and the maximum value of 11.
55+
56+
-or-
57+
58+
<paramref name="window" /> is not between the minimum value of 10 and the maximum value of 24.
59+
</exception>
60+
<exception cref="T:System.IO.IOException">Failed to create the <see cref="T:System.IO.Compression.BrotliEncoder" /> instance.</exception>
5461
</Docs>
5562
</Member>
5663
<Member MemberName="Compress">
@@ -80,13 +87,13 @@
8087
<Parameter Name="isFinalBlock" Type="System.Boolean" />
8188
</Parameters>
8289
<Docs>
83-
<param name="source">To be added.</param>
84-
<param name="destination">To be added.</param>
85-
<param name="bytesConsumed">To be added.</param>
86-
<param name="bytesWritten">To be added.</param>
87-
<param name="isFinalBlock">To be added.</param>
88-
<summary>To be added.</summary>
89-
<returns>To be added.</returns>
90+
<param name="source">A read-only span of bytes containing the source data to compress.</param>
91+
<param name="destination">When this method returns, a byte span where the compressed is stored.</param>
92+
<param name="bytesConsumed">When this method returns, the total number of bytes that were read from <paramref name="source" />.</param>
93+
<param name="bytesWritten">When this method returns, the total number of bytes that were written to <paramref name="destination" />.</param>
94+
<param name="isFinalBlock"><see langword="true" /> to finalize the internal stream, which prevents adding more input data when this method returns; <see langword="false" /> to allow the encoder to postpone the production of output until it has processed enough input.</param>
95+
<summary>Compresses a read-only byte span into a destination span.</summary>
96+
<returns>One of the enumeration values that describes the status with which the span-based operation finished.</returns>
9097
<remarks>To be added.</remarks>
9198
</Docs>
9299
</Member>
@@ -114,7 +121,7 @@
114121
</ReturnValue>
115122
<Parameters />
116123
<Docs>
117-
<summary>To be added.</summary>
124+
<summary>Frees and disposes unmanaged resources.</summary>
118125
<remarks>To be added.</remarks>
119126
</Docs>
120127
</Member>
@@ -142,10 +149,10 @@
142149
<Parameter Name="bytesWritten" Type="System.Int32" RefType="out" />
143150
</Parameters>
144151
<Docs>
145-
<param name="destination">To be added.</param>
146-
<param name="bytesWritten">To be added.</param>
147-
<summary>To be added.</summary>
148-
<returns>To be added.</returns>
152+
<param name="destination">When this method returns, a span of bytes where the compressed data will be stored.</param>
153+
<param name="bytesWritten">When this method returns, the total number of bytes that were written to <paramref name="destination" />.</param>
154+
<summary>Compresses an empty read-only span of bytes into its destination, which ensures that output is produced for all the processed input. An actual flush is performed when the source is depleted and there is enough space in the destination for the remaining data.</summary>
155+
<returns>One of the enumeration values that describes the status with which the operation finished.</returns>
149156
<remarks>To be added.</remarks>
150157
</Docs>
151158
</Member>
@@ -172,10 +179,19 @@
172179
<Parameter Name="inputSize" Type="System.Int32" />
173180
</Parameters>
174181
<Docs>
175-
<param name="inputSize">To be added.</param>
176-
<summary>To be added.</summary>
177-
<returns>To be added.</returns>
178-
<remarks>To be added.</remarks>
182+
<param name="inputSize">The input size to get the maximum expected compressed length from. Must be greater or equal than 0 and less or equal than <see cref="P:System.Int32.MaxValue" /> - 515.</param>
183+
<summary>Gets the maximum expected compressed length for the provided input size.</summary>
184+
<returns>A number representing the maximum compressed length for the provided input size.</returns>
185+
<remarks>
186+
<format type="text/markdown"><![CDATA[
187+
188+
## Remarks
189+
190+
Returns 1 if `inputSize` is 0.
191+
192+
]]></format>
193+
</remarks>
194+
<exception cref="T:System.ArgumentOutOfRangeException"><paramref name="inputSize" /> is less than 0, the minimum allowed input size, or greater than <see cref="P:System.Int32.MaxValue" /> - 515, the maximum allowed input size.</exception>
179195
</Docs>
180196
</Member>
181197
<Member MemberName="TryCompress">
@@ -203,11 +219,11 @@
203219
<Parameter Name="bytesWritten" Type="System.Int32" RefType="out" />
204220
</Parameters>
205221
<Docs>
206-
<param name="source">To be added.</param>
207-
<param name="destination">To be added.</param>
208-
<param name="bytesWritten">To be added.</param>
209-
<summary>To be added.</summary>
210-
<returns>To be added.</returns>
222+
<param name="source">A read-only span of bytes containing the source data to compress.</param>
223+
<param name="destination">When this method returns, a span of bytes where the compressed data is stored.</param>
224+
<param name="bytesWritten">When this method returns, the total number of bytes that were written to <paramref name="destination" />.</param>
225+
<summary>Tries to compress a source byte span into a destination span.</summary>
226+
<returns><see langword="true" /> if the compression operation was successful; <see langword="false" /> otherwise.</returns>
211227
<remarks>To be added.</remarks>
212228
</Docs>
213229
</Member>
@@ -238,13 +254,13 @@
238254
<Parameter Name="window" Type="System.Int32" />
239255
</Parameters>
240256
<Docs>
241-
<param name="source">To be added.</param>
242-
<param name="destination">To be added.</param>
243-
<param name="bytesWritten">To be added.</param>
244-
<param name="quality">To be added.</param>
245-
<param name="window">To be added.</param>
246-
<summary>To be added.</summary>
247-
<returns>To be added.</returns>
257+
<param name="source">A read-only span of bytes containing the source data to compress.</param>
258+
<param name="destination">When this method returns, a span of bytes where the compressed data is stored.</param>
259+
<param name="bytesWritten">When this method returns, the total number of bytes that were written to <paramref name="destination" />.</param>
260+
<param name="quality">A number representing quality of the Brotli compression. 0 is the minimum (no compression), 11 is the maximum.</param>
261+
<param name="window">A number representing the encoder window bits. The minimum value is 10, and the maximum value is 24.</param>
262+
<summary>Tries to compress a source byte span into a destination byte span, using the provided compression quality leven and encoder window bits.</summary>
263+
<returns><see langword="true" /> if the compression operation was successful; <see langword="false" /> otherwise.</returns>
248264
<remarks>To be added.</remarks>
249265
</Docs>
250266
</Member>

‎xml/System.IO.Compression/BrotliStream.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -126,7 +126,7 @@
126126
<Docs>
127127
<param name="stream">The stream to compress.</param>
128128
<param name="mode">One of the enumeration values that indicates whether to compress or decompress the stream.</param>
129-
<param name="leaveOpen">To be added.</param>
129+
<param name="leaveOpen"><see langword="true" /> to leave the stream open after the <see cref="T:System.IO.Compression.BrotliStream" /> object is disposed; otherwise, <see langword="false" />.</param>
130130
<summary>Initializes a new instance of the <see cref="T:System.IO.Compression.BrotliStream" /> class by using the specified stream and compression mode, and optionally leaves the stream open.</summary>
131131
<remarks>To be added.</remarks>
132132
</Docs>

0 commit comments

Comments
 (0)