Backport System.IO.Compression docs #48841

carlossanlop · 2021-02-26T18:55:25Z

Includes types from System.IO.Compression, except those found in Compression.ZipFile (PR in review) and Compression.Brotli (merged PR).

Backport automated using DocsPortingTool with this command:

DocsPortingTool.exe \
-CsProj D:\runtime\src\libraries\System.IO.Compression\src\System.IO.Compression.csproj \
-Docs D:\dotnet-api-docs\xml \
-Direction ToTripleSlash \
-IncludedAssemblies System.IO.Compression \
-IncludedNamespaces System.IO.Compression

Related PRs:

Move Compression lengthy remarks to their own files: Move System.IO.Compression lengthy remarks to files dotnet-api-docs#5378
Remove shortcuts from dotnet-api-docs: Remove md shortcuts and their references dotnet-api-docs#5372

Please review by comparing against the files of origin (keep in mind what the related PRs are changing): https://github.com/dotnet/dotnet-api-docs/tree/master/xml/System.IO.Compression

… cannot be referenced. Add O: prefix to method overloads.

…hyperlinks in xml, overload crefs,

carlossanlop

Pending reviewing more files.

carlossanlop · 2021-02-26T18:58:55Z

src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionLevel.cs

-
-    // This is an abstract concept and NOT the ZLib compression level.
-    // There may or may not be any correspondence with the a possible implementation-specific level-parameter of the deflater.
+    /// <summary>Specifies values that indicate whether a compression operation emphasizes speed or compression size.</summary>


These double slash comments should probably stay:

Suggested change

/// <summary>Specifies values that indicate whether a compression operation emphasizes speed or compression size.</summary>

// This is an abstract concept and NOT the ZLib compression level.

// There may or may not be any correspondence with the a possible implementation-specific level-parameter of the deflater.

/// <summary>Specifies values that indicate whether a compression operation emphasizes speed or compression size.</summary>

carlossanlop · 2021-02-26T19:00:13Z

src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs

+        /// [!code-vb[System.IO.Compression.DeflateStream#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.deflatestream/vb/program1.vb#1)]
+        /// ]]></format></example>
+        /// <exception cref="System.ArgumentNullException"><paramref name="stream" /> is <see langword="null" />.</exception>
+        /// <exception cref="System.ArgumentException">The stream does not support write operations such as compression. (The <see cref="System.IO.Stream.CanWrite" /> property on the stream object is <see langword="false" />.)</exception>
        public DeflateStream(Stream stream, CompressionLevel compressionLevel) : this(stream, compressionLevel, leaveOpen: false)


Double slash comments should probably stay, but I'll move them here:

Suggested change

public DeflateStream(Stream stream, CompressionLevel compressionLevel) : this(stream, compressionLevel, leaveOpen: false)

// Implies mode = Compress

public DeflateStream(Stream stream, CompressionLevel compressionLevel) : this(stream, compressionLevel, leaveOpen: false)

carlossanlop · 2021-02-26T19:00:30Z

src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs

+        /// [!INCLUDE[remarks](~/includes/remarks/System.IO.Compression/DeflateStream/.ctor_Stream_CompressionLevel_Boolean.md)]
+        /// ]]></format></remarks>
+        /// <exception cref="System.ArgumentNullException"><paramref name="stream" /> is <see langword="null" />.</exception>
+        /// <exception cref="System.ArgumentException">The stream does not support write operations such as compression. (The <see cref="System.IO.Stream.CanWrite" /> property on the stream object is <see langword="false" />.)</exception>
        public DeflateStream(Stream stream, CompressionLevel compressionLevel, bool leaveOpen) : this(stream, compressionLevel, leaveOpen, ZLibNative.Deflate_DefaultWindowBits)


Suggested change

public DeflateStream(Stream stream, CompressionLevel compressionLevel, bool leaveOpen) : this(stream, compressionLevel, leaveOpen, ZLibNative.Deflate_DefaultWindowBits)

// Implies mode = Compress

public DeflateStream(Stream stream, CompressionLevel compressionLevel, bool leaveOpen) : this(stream, compressionLevel, leaveOpen, ZLibNative.Deflate_DefaultWindowBits)

carlossanlop · 2021-02-26T19:20:59Z

src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs

+        /// <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>
+        /// <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>
+        /// <remarks>Use the <see cref="System.IO.Compression.DeflateStream.CanRead" /> property to determine whether the current instance supports reading. Use the <see cref="O:System.IO.Compression.DeflateStream.ReadAsync" /> method to read asynchronously from the current stream.
+        /// This method read a maximum of `buffer.Length` bytes from the current stream and store them in <paramref name="buffer" />. The current position within the Deflate stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the Deflate 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.


Need to double check the cref on VS for the Span argument:

Suggested change

/// This method read a maximum of `buffer.Length` bytes from the current stream and store them in <paramref name="buffer" />. The current position within the Deflate stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the Deflate 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.

/// This method read a maximum of <c>buffer.Length</c> bytes from the current stream and store them in <paramref name="buffer" />. The current position within the Deflate stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the Deflate 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. <see cref="System.IO.Compression.DeflateStream.Read(System.Span<System.Byte>)" /> 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.

carlossanlop · 2021-02-26T19:22:53Z

src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs

+        /// <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="System.Threading.CancellationToken.None" />.</param>
+        /// <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 Deflate stream has been reached.</returns>
+        /// <remarks>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 Windows 8.x Store app or desktop 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 <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.


Need to double check the cref signature in VS:

Suggested change

/// <remarks>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 Windows 8.x Store app or desktop 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 <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.

/// <remarks>The <see cref="System.IO.Compression.DeflateStream.ReadAsync(System.Byte[],System.Int32,System.Int32,System.Threading.CancellationToken)" /> method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The asynchronous methods are used in conjunction with the <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.

carlossanlop · 2021-02-26T19:23:47Z

src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs

+        /// <param name="buffer">The region of memory to write the data into.</param>
+        /// <param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="System.Threading.CancellationToken.None" />.</param>
+        /// <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 Deflate stream has been reached.</returns>
+        /// <remarks>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 Windows 8.x Store app or desktop 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 <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.


Need to double check the signature:

Suggested change

/// <remarks>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 Windows 8.x Store app or desktop 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 <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.

/// <remarks>The <see cref="System.IO.Compression.DeflateStream.ReadAsync(System.Memory<System.Byte>,System.Threading.CancellationToken)" /> method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The asynchronous methods are used in conjunction with the <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.

carlossanlop · 2021-02-26T19:24:39Z

src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs

+        /// <remarks>The `DisposeAsync` method enables you to perform a resource-intensive dispose operation without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop 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 <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.
+        /// This method disposes the Deflate stream by writing any changes to the backing store and closing the stream to release resources.
+        /// Calling `DisposeAsync` allows the resources used by the <see cref="System.IO.Compression.DeflateStream" /> to be reallocated for other purposes. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged).</remarks>


Suggested change

/// <remarks>The `DisposeAsync` method enables you to perform a resource-intensive dispose operation without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop 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 <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.

/// This method disposes the Deflate stream by writing any changes to the backing store and closing the stream to release resources.

/// Calling `DisposeAsync` allows the resources used by the <see cref="System.IO.Compression.DeflateStream" /> to be reallocated for other purposes. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged).</remarks>

/// <remarks>The <see cref="System.IO.Compression.DeflateStream.DisposeAsync()" /> method enables you to perform a resource-intensive dispose operation without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop 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 <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.

/// This method disposes the Deflate stream by writing any changes to the backing store and closing the stream to release resources.

/// Calling <see cref="System.IO.Compression.DeflateStream.DisposeAsync()" /> allows the resources used by the <see cref="System.IO.Compression.DeflateStream" /> to be reallocated for other purposes. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged).</remarks>

carlossanlop · 2021-02-26T19:25:35Z

src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs

+        /// <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="System.Threading.CancellationToken.None" />.</param>
+        /// <returns>A task that represents the asynchronous write operation.</returns>
+        /// <remarks>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 Windows 8.x Store app or desktop 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 <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.


Suggested change

/// <remarks>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 Windows 8.x Store app or desktop 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 <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.

/// <remarks>The <see cref="System.IO.Compression.DeflateStream.WriteAsync(System.Byte[],System.Int32,System.Int32,System.Threading.CancellationToken)" /> method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The asynchronous methods are used in conjunction with the <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.

carlossanlop · 2021-02-26T19:26:11Z

src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs

+        /// <param name="buffer">The region of memory to write data from.</param>
+        /// <param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="System.Threading.CancellationToken.None" />.</param>
+        /// <returns>A task that represents the asynchronous write operation.</returns>
+        /// <remarks>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 Windows 8.x Store app or desktop 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 <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.


Suggested change

/// <remarks>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 Windows 8.x Store app or desktop 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 <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.

/// <remarks>The <see cref="System.IO.Compression.DeflateStream.WriteAsync(System.ReadOnlyMemory<System.Byte>,System.Threading.CancellationToken)" /> method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The asynchronous methods are used in conjunction with the <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.

carlossanlop · 2021-02-26T19:26:48Z

src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs

+        /// <param name="bufferSize">The size, in bytes, of the buffer. This value must be greater than zero. The default size is 81920.</param>
+        /// <param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="System.Threading.CancellationToken.None" />.</param>
+        /// <returns>A task that represents the asynchronous copy operation.</returns>
+        /// <remarks>The `CopyToAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop 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 <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.


Suggested change

/// <remarks>The `CopyToAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop 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 <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.

/// <remarks>The <see cref="System.IO.Compression.DeflateStream.CopyToAsync(System.IO.Stream,System.Int32,System.Threading.CancellationToken)" /> method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The asynchronous methods are used in conjunction with the <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.

jozkee · 2021-03-02T00:06:41Z

src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionLevel.cs

-    // There may or may not be any correspondence with the a possible implementation-specific level-parameter of the deflater.
+    /// <summary>Specifies values that indicate whether a compression operation emphasizes speed or compression size.</summary>
+    /// <remarks><format type="text/markdown"><![CDATA[
+    /// [!INCLUDE[remarks](~/includes/remarks/System.IO.Compression/CompressionLevel/CompressionLevel.md)]


This link can't be followed from runtime's source... is there a value on porting it? Perhaps you could ignore it and keep the source of truth in dotnet-api-docs.

My understanding from the docs is that we do want to port these links over.

jozkee · 2021-03-02T00:19:01Z

src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionLevel.cs

-        /// <summary>
-        /// The compression operation should balance compression speed and output size.
-        /// </summary>
+        /// <summary>The compression operation should be optimally compressed, even if the operation takes a longer time to complete.</summary>


Old and new sentences are describing completely different behaviors, do you know if the new one is actually true?

Yeah, it seems it should be written as:

/// <summary>The compression operation should be optimally compressed, balancing compression speed and output size.</summary>

jozkee · 2021-03-02T00:23:13Z

src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionMode.cs

+    /// <remarks>This enumeration is used with the <see cref="System.IO.Compression.GZipStream" /> and <see cref="System.IO.Compression.DeflateStream" /> classes.</remarks>
+    /// <example>The following code example uses the <see cref="System.IO.Compression.CompressionMode" /> enumeration with the <see cref="System.IO.Compression.GZipStream" /> class to compress and decompress a file.
+    /// <format type="text/markdown"><![CDATA[
+    /// [!code-csharp[IO.Compression.GZip1#1](~/samples/snippets/csharp/VS_Snippets_CLR/IO.Compression.GZip1/CS/gziptest.cs#1)]


Same comment as #48841 (comment).

jozkee · 2021-03-02T00:37:45Z

src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs

+        /// The underlying stream does not support reading.</exception>
+        /// <exception cref="System.ArgumentOutOfRangeException"><paramref name="offset" /> or <paramref name="count" /> is less than zero.
+        /// -or-
+        /// <paramref name="buffer" /> length minus the index starting point is less than <paramref name="count" />.</exception>


The argument buffer is called array in the docs... should docs be changed?

https://docs.microsoft.com/dotnet/api/system.io.compression.deflatestream.read?view=net-5.0#System_IO_Compression_DeflateStream_Read_System_Byte___System_Int32_System_Int32_

It looks like it was renamed in October with 0acbafe#diff-a076647d6d5119e4e3b482835f098318b585fc7fd9cb16116c45395721c61c3d.

What release is that in? And do we need to document it as a breaking change?

@gewarren right, it is a breaking change that is going to ship with 6.0; it seems that the introducing PR #43834 is already tagged with the breaking-change and the needs-breaking-change-doc-created labels.

jozkee · 2021-03-02T02:15:08Z

src/libraries/System.IO.Compression/src/System/IO/Compression/GZipStream.cs

        public GZipStream(Stream stream, CompressionMode mode, bool leaveOpen)
        {
            _deflateStream = new DeflateStream(stream, mode, leaveOpen, ZLibNative.GZip_DefaultWindowBits);
        }

-        // Implies mode = Compress


Another double-slash comment lost.

jozkee · 2021-03-02T02:15:15Z

src/libraries/System.IO.Compression/src/System/IO/Compression/GZipStream.cs

        public GZipStream(Stream stream, CompressionLevel compressionLevel) : this(stream, compressionLevel, leaveOpen: false)
        {
        }

-        // Implies mode = Compress


jozkee · 2021-03-02T02:26:44Z

src/libraries/System.IO.Compression/src/System/IO/Compression/GZipStream.cs

+        /// <summary>Waits for the pending asynchronous read to complete. (Consider using the <see cref="System.IO.Stream.ReadAsync(byte[],int,int)" /> method instead.)</summary>
+        /// <param name="asyncResult">The reference to the pending asynchronous request to finish.</param>
+        /// <returns>The number of bytes read from the stream, between 0 (zero) and the number of bytes you requested. <see cref="System.IO.Compression.GZipStream" /> returns 0 only at the end of the stream; otherwise, it blocks until at least one byte is available.</returns>
+        /// <remarks>Starting with the .NET Framework 4.5, you can perform asynchronous read operations by using the <see cref="O:System.IO.Stream.ReadAsync" /> method. The <see cref="System.IO.Compression.GZipStream.EndRead" /> method is still available in .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see <a href="https://docs.microsoft.com/en-us/dotnet/standard/io/asynchronous-file-i-o">Asynchronous File I/O</a>.


What does the O: in <see cref="O:System.IO.Stream.ReadAsync" /> mean?

It is for referencing an overloaded method. Notes here.

jozkee · 2021-03-02T02:52:34Z

src/libraries/System.IO.Compression/src/System/IO/Compression/GZipStream.cs

        public override void CopyTo(Stream destination, int bufferSize)
        {
            CheckDeflateStream();
            _deflateStream.CopyTo(destination, bufferSize);
        }

+        /// <summary>Releases the unmanaged resources used by the <see cref="System.IO.Compression.GZipStream" /> and optionally releases the managed resources.</summary>
+        /// <param name="disposing"><see langword="true" /> to release both managed and unmanaged resources; <see langword="false" /> to release only unmanaged resources.</param>
+        /// <remarks>This method is called by the public <see langword="System.ComponentModel.Component.Dispose" /> method and the <see cref="object.Finalize" /> method. <see langword="System.ComponentModel.Component.Dispose" /> invokes the protected <see cref="System.IO.Compression.GZipStream.Dispose" /> method with the <paramref name="disposing" /> parameter set to <see langword="true" />. <see cref="object.Finalize" /> invokes <see cref="System.IO.Compression.GZipStream.Dispose" /> with <paramref name="disposing" /> set to <see langword="false" />.


Shouldn't it be <see cref="...Dispose" /> instead of <see langword="...Dispose" />?

You're correct; good catch @jozkee!

Suggested change

/// <remarks>This method is called by the public <see langword="System.ComponentModel.Component.Dispose" /> method and the <see cref="object.Finalize" /> method. <see langword="System.ComponentModel.Component.Dispose" /> invokes the protected <see cref="System.IO.Compression.GZipStream.Dispose" /> method with the <paramref name="disposing" /> parameter set to <see langword="true" />. <see cref="object.Finalize" /> invokes <see cref="System.IO.Compression.GZipStream.Dispose" /> with <paramref name="disposing" /> set to <see langword="false" />.

/// <remarks>This method is called by the public <see cref="System.ComponentModel.Component.Dispose" /> method and the <see cref="object.Finalize" /> method. <see cref="System.ComponentModel.Component.Dispose" /> invokes the protected <see cref="System.IO.Compression.GZipStream.Dispose" /> method with the <paramref name="disposing" /> parameter set to <see langword="true" />. <see cref="object.Finalize" /> invokes <see cref="System.IO.Compression.GZipStream.Dispose" /> with <paramref name="disposing" /> set to <see langword="false" />.

jozkee · 2021-03-02T03:00:35Z

src/libraries/System.IO.Compression/src/System/IO/Compression/GZipStream.cs

+        /// <param name="buffer">The region of memory to write the data into.</param>
+        /// <param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="System.Threading.CancellationToken.None" />.</param>
+        /// <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 GZip stream has been reached.</returns>
+        /// <remarks>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 Windows 8.x Store app or desktop 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 <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.


Suggested change

/// <remarks>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 Windows 8.x Store app or desktop 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 <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.

/// <remarks>The <see cref="System.IO.Compression.GZipStream.ReadAsync" /> method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop 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 <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.

jozkee · 2021-03-02T03:01:01Z

src/libraries/System.IO.Compression/src/System/IO/Compression/GZipStream.cs

+        /// <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="System.Threading.CancellationToken.None" />.</param>
+        /// <returns>A task that represents the asynchronous write operation.</returns>
+        /// <remarks>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 Windows 8.x Store app or desktop 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 <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.


Suggested change

/// <remarks>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 Windows 8.x Store app or desktop 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 <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.

/// <remarks>The <see cref="System.IO.Compression.GZipStream.WriteAsync" /> method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop 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 <see langword="async" /> and <see langword="await" /> keywords in Visual Basic and C#.

jozkee · 2021-03-02T03:06:50Z

src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchive.cs

-#if DEBUG_FORCE_ZIP64
-        public bool _forceZip64;
-#endif


This doesn't look like something that should be removed in this PR.

Good catch. I've been working on dotnet/api-docs-sync#65, but we'll have to manually fix it here.

jozkee · 2021-03-02T03:14:10Z

src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchive.cs

        /// <param name="stream">The input or output stream.</param>
-        /// <param name="mode">See the description of the ZipArchiveMode enum. Read requires the stream to support reading, Create requires the stream to support writing, and Update requires the stream to support reading, writing, and seeking.</param>
-        /// <param name="leaveOpen">true to leave the stream open upon disposing the ZipArchive, otherwise false.</param>
-        /// <param name="entryNameEncoding">The encoding to use when reading or writing entry names in this ZipArchive.


Is the info in this param still relevant? Seems that it is not captured in the documentation page for this ctor

https://docs.microsoft.com/en-us/dotnet/api/system.io.compression.ziparchive.-ctor?view=net-5.0#System_IO_Compression_ZipArchive__ctor_System_IO_Stream_System_IO_Compression_ZipArchiveMode_System_Boolean_System_Text_Encoding_

jozkee · 2021-03-02T03:16:29Z

src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchive.cs

@@ -211,12 +184,17 @@ public ZipArchive(Stream stream, ZipArchiveMode mode, bool leaveOpen, Encoding?
            }
        }

-        /// <summary>
-        /// The collection of entries that are currently in the ZipArchive. This may not accurately represent the actual entries that are present in the underlying file or stream.


This may not accurately represent the actual entries that are present in the underlying file or stream.

This is not captured anywhere in the documentation page https://docs.microsoft.com/en-us/dotnet/api/system.io.compression.ziparchive.entries?view=net-5.0

jozkee · 2021-03-02T03:45:15Z

src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.cs

@@ -278,13 +297,23 @@ public void Delete()
            UnloadStreams();
        }

-        /// <summary>
-        /// Opens the entry. If the archive that the entry belongs to was opened in Read mode, the returned stream will be readable, and it may or may not be seekable. If Create mode, the returned stream will be writable and not seekable. If Update mode, the returned stream will be readable, writable, seekable, and support SetLength.


If the archive that the entry belongs to was opened in Read mode, the returned stream will be readable, and it may or may not be seekable. If Create mode, the returned stream will be writable and not seekable. If Update mode, the returned stream will be readable, writable, seekable, and support SetLength.

Consider adding this to https://docs.microsoft.com/en-us/dotnet/api/system.io.compression.ziparchiveentry.open?view=net-5.0.

jozkee

Otherwise; LGTM.

sharwell · 2021-03-02T04:04:41Z

src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionMode.cs

@@ -3,9 +3,18 @@

 namespace System.IO.Compression
 {
+    /// <summary>Specifies whether to compress or decompress the underlying stream.</summary>
+    /// <remarks>This enumeration is used with the <see cref="System.IO.Compression.GZipStream" /> and <see cref="System.IO.Compression.DeflateStream" /> classes.</remarks>


We should fix the formatting of these tags before running the automation on everything.

Suggested change

/// <remarks>This enumeration is used with the <see cref="System.IO.Compression.GZipStream" /> and <see cref="System.IO.Compression.DeflateStream" /> classes.</remarks>

/// <remarks>This enumeration is used with the <see cref="System.IO.Compression.GZipStream"/> and <see cref="System.IO.Compression.DeflateStream"/> classes.</remarks>

We've always had the space character in there in dotnet-api-docs.

VS does not insert the trailing space before the slash. I've wondered if it would be better to be consistent with what VS is going to do. I've opened dotnet/api-docs-sync#73 for that, but we don't need to block this PR on that issue; we can run a revision run to reformat.

sharwell · 2021-03-02T04:06:49Z

src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.cs

+        /// <exception cref="System.IO.IOException">The entry is already currently open for writing.
+        /// -or-
+        /// The entry has been deleted from the archive.
+        /// -or-
+        /// The archive for this entry was opened with the <see cref="System.IO.Compression.ZipArchiveMode.Create" /> mode, and this entry has already been written to.</exception>
+        /// <exception cref="System.IO.InvalidDataException">The entry is either missing from the archive or is corrupt and cannot be read.
+        /// -or-
+        /// The entry has been compressed by using a compression method that is not supported.</exception>


All the required <para> elements are missing

Suggested change

/// <exception cref="System.IO.IOException">The entry is already currently open for writing.

/// -or-

/// The entry has been deleted from the archive.

/// -or-

/// The archive for this entry was opened with the <see cref="System.IO.Compression.ZipArchiveMode.Create" /> mode, and this entry has already been written to.</exception>

/// <exception cref="System.IO.InvalidDataException">The entry is either missing from the archive or is corrupt and cannot be read.

/// -or-

/// The entry has been compressed by using a compression method that is not supported.</exception>

/// <exception cref="System.IO.IOException"><para>The entry is already currently open for writing.</para>

/// <para>-or-</para>

/// <para>The entry has been deleted from the archive.</para>

/// <para>-or-</para>

/// <para>The archive for this entry was opened with the <see cref="System.IO.Compression.ZipArchiveMode.Create" /> mode, and this entry has already been written to.</para></exception>

/// <exception cref="System.IO.InvalidDataException"><para>The entry is either missing from the archive or is corrupt and cannot be read.</para>

/// <para>-or-</para>

/// <para>The entry has been compressed by using a compression method that is not supported.</para></exception>

gewarren · 2021-03-09T23:32:30Z

src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs

        public override long Position
        {
            get { throw new NotSupportedException(SR.NotSupported); }
            set { throw new NotSupportedException(SR.NotSupported); }
        }

+        /// <summary>The current implementation of this method has no functionality.</summary>


The summary doesn't seem correct.

jeffhandley · 2021-04-18T06:13:35Z

src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionLevel.cs

-    // There may or may not be any correspondence with the a possible implementation-specific level-parameter of the deflater.
+    /// <summary>Specifies values that indicate whether a compression operation emphasizes speed or compression size.</summary>
+    /// <remarks><format type="text/markdown"><![CDATA[
+    /// [!INCLUDE[remarks](~/includes/remarks/System.IO.Compression/CompressionLevel/CompressionLevel.md)]


My understanding from the docs is that we do want to port these links over.

jeffhandley · 2021-04-18T06:16:27Z

src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionLevel.cs

-        /// <summary>
-        /// The compression operation should balance compression speed and output size.
-        /// </summary>
+        /// <summary>The compression operation should be optimally compressed, even if the operation takes a longer time to complete.</summary>


Yeah, it seems it should be written as:

/// <summary>The compression operation should be optimally compressed, balancing compression speed and output size.</summary>

jeffhandley · 2021-04-18T06:20:35Z

src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionMode.cs

@@ -3,9 +3,18 @@

 namespace System.IO.Compression
 {
+    /// <summary>Specifies whether to compress or decompress the underlying stream.</summary>
+    /// <remarks>This enumeration is used with the <see cref="System.IO.Compression.GZipStream" /> and <see cref="System.IO.Compression.DeflateStream" /> classes.</remarks>


VS does not insert the trailing space before the slash. I've wondered if it would be better to be consistent with what VS is going to do. I've opened dotnet/api-docs-sync#73 for that, but we don't need to block this PR on that issue; we can run a revision run to reformat.

jeffhandley · 2021-04-18T06:23:25Z

src/libraries/System.IO.Compression/src/System/IO/Compression/GZipStream.cs

+        /// [!code-vb[System.IO.Compression.GZipStream#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.gzipstream/vb/program1.vb#1)]
+        /// ]]></format></example>
+        /// <exception cref="System.ArgumentNullException"><paramref name="stream" /> is <see langword="null" />.</exception>
+        /// <exception cref="System.ArgumentException">The stream does not support write operations such as compression. (The <see cref="System.IO.Stream.CanWrite" /> property on the stream object is <see langword="false" />.)</exception>
        public GZipStream(Stream stream, CompressionLevel compressionLevel) : this(stream, compressionLevel, leaveOpen: false)


Suggested change

public GZipStream(Stream stream, CompressionLevel compressionLevel) : this(stream, compressionLevel, leaveOpen: false)

// Implies mode = Compress

public GZipStream(Stream stream, CompressionLevel compressionLevel) : this(stream, compressionLevel, leaveOpen: false)

jeffhandley · 2021-04-18T06:23:52Z

src/libraries/System.IO.Compression/src/System/IO/Compression/GZipStream.cs

+        /// [!code-vb[System.IO.Compression.GZipStream#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.gzipstream/vb/program2.vb#2)]
+        /// ]]></format></example>
+        /// <exception cref="System.ArgumentNullException"><paramref name="stream" /> is <see langword="null" />.</exception>
+        /// <exception cref="System.ArgumentException">The stream does not support write operations such as compression. (The <see cref="System.IO.Stream.CanWrite" /> property on the stream object is <see langword="false" />.)</exception>
        public GZipStream(Stream stream, CompressionLevel compressionLevel, bool leaveOpen)


Suggested change

public GZipStream(Stream stream, CompressionLevel compressionLevel, bool leaveOpen)

// Implies mode = Compress

public GZipStream(Stream stream, CompressionLevel compressionLevel, bool leaveOpen)

jeffhandley · 2021-04-18T06:26:53Z

src/libraries/System.IO.Compression/src/System/IO/Compression/GZipStream.cs

+        /// <summary>Waits for the pending asynchronous read to complete. (Consider using the <see cref="System.IO.Stream.ReadAsync(byte[],int,int)" /> method instead.)</summary>
+        /// <param name="asyncResult">The reference to the pending asynchronous request to finish.</param>
+        /// <returns>The number of bytes read from the stream, between 0 (zero) and the number of bytes you requested. <see cref="System.IO.Compression.GZipStream" /> returns 0 only at the end of the stream; otherwise, it blocks until at least one byte is available.</returns>
+        /// <remarks>Starting with the .NET Framework 4.5, you can perform asynchronous read operations by using the <see cref="O:System.IO.Stream.ReadAsync" /> method. The <see cref="System.IO.Compression.GZipStream.EndRead" /> method is still available in .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see <a href="https://docs.microsoft.com/en-us/dotnet/standard/io/asynchronous-file-i-o">Asynchronous File I/O</a>.


It is for referencing an overloaded method. Notes here.

jeffhandley · 2021-04-18T06:27:39Z

src/libraries/System.IO.Compression/src/System/IO/Compression/GZipStream.cs

        public override void CopyTo(Stream destination, int bufferSize)
        {
            CheckDeflateStream();
            _deflateStream.CopyTo(destination, bufferSize);
        }

+        /// <summary>Releases the unmanaged resources used by the <see cref="System.IO.Compression.GZipStream" /> and optionally releases the managed resources.</summary>
+        /// <param name="disposing"><see langword="true" /> to release both managed and unmanaged resources; <see langword="false" /> to release only unmanaged resources.</param>
+        /// <remarks>This method is called by the public <see langword="System.ComponentModel.Component.Dispose" /> method and the <see cref="object.Finalize" /> method. <see langword="System.ComponentModel.Component.Dispose" /> invokes the protected <see cref="System.IO.Compression.GZipStream.Dispose" /> method with the <paramref name="disposing" /> parameter set to <see langword="true" />. <see cref="object.Finalize" /> invokes <see cref="System.IO.Compression.GZipStream.Dispose" /> with <paramref name="disposing" /> set to <see langword="false" />.


You're correct; good catch @jozkee!

Suggested change

/// <remarks>This method is called by the public <see langword="System.ComponentModel.Component.Dispose" /> method and the <see cref="object.Finalize" /> method. <see langword="System.ComponentModel.Component.Dispose" /> invokes the protected <see cref="System.IO.Compression.GZipStream.Dispose" /> method with the <paramref name="disposing" /> parameter set to <see langword="true" />. <see cref="object.Finalize" /> invokes <see cref="System.IO.Compression.GZipStream.Dispose" /> with <paramref name="disposing" /> set to <see langword="false" />.

/// <remarks>This method is called by the public <see cref="System.ComponentModel.Component.Dispose" /> method and the <see cref="object.Finalize" /> method. <see cref="System.ComponentModel.Component.Dispose" /> invokes the protected <see cref="System.IO.Compression.GZipStream.Dispose" /> method with the <paramref name="disposing" /> parameter set to <see langword="true" />. <see cref="object.Finalize" /> invokes <see cref="System.IO.Compression.GZipStream.Dispose" /> with <paramref name="disposing" /> set to <see langword="false" />.

jeffhandley · 2021-04-18T06:29:45Z

src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchive.cs

-#if DEBUG_FORCE_ZIP64
-        public bool _forceZip64;
-#endif


Good catch. I've been working on dotnet/api-docs-sync#65, but we'll have to manually fix it here.

jeffhandley · 2021-04-18T06:30:54Z

src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchive.cs

-        /// <exception cref="ArgumentNullException">The stream is null.</exception>
-        /// <exception cref="InvalidDataException">The contents of the stream could not be interpreted as a Zip archive.</exception>
-        /// <param name="stream">The stream containing the archive to be read.</param>
+        /// <summary>Initializes a new instance of the <see cref="System.IO.Compression.ZipArchive" /> class from the specified stream.</summary>


Suggested change

/// <summary>Initializes a new instance of the <see cref="System.IO.Compression.ZipArchive" /> class from the specified stream.</summary>

#if DEBUG_FORCE_ZIP64

public bool _forceZip64;

#endif

/// <summary>Initializes a new instance of the <see cref="System.IO.Compression.ZipArchive" /> class from the specified stream.</summary>

ghost · 2021-05-18T10:00:13Z

Draft Pull Request was automatically closed for inactivity. Please let us know if you'd like to reopen it.

carlossanlop added 18 commits February 25, 2021 15:48

DeflateStream

ed98733

CompressionLevel

986d1ea

CompressionMode

d4bae09

GZipStream

f0628ad

ZipArchive

46f53e7

ZipArchiveEntry

35c4164

ZipArchiveEntry.Windows

c3e5092

ZipArchiveMode

e7bc9f2

Remove duplicate or inexistent parameters. Use langword for APIs that…

d113f4b

… cannot be referenced. Add O: prefix to method overloads.

Use langwords for APIs that cannot be referenced.

c5cc992

DeflateStream unresolved hyperlinks in xml.

6dd0ac6

GZipStream #ctor to actual method, array param to buffer, unresolved …

9ded70b

…hyperlinks in xml, overload crefs,

ZipArchive: langword, #ctor, hyperlinks, overloads

396c83a

ZipArchiveEntry: langwords, overloads

99bf1b6

ZipArchiveEntry.Windows: langword, hyperlinks, overloads

ebda19e

ZipArchiveMode: langword, #ctor

328f7c4

Lengthy remarks

e250401

GenerateDocumentationFile in csproj

2186185

carlossanlop added documentation Documentation bug or enhancement, does not impact product or test code area-System.IO.Compression labels Feb 26, 2021

carlossanlop added this to the 6.0.0 milestone Feb 26, 2021

carlossanlop requested review from jeffhandley, adamsitnik, jozkee and gewarren February 26, 2021 18:55

carlossanlop self-assigned this Feb 26, 2021

carlossanlop commented Feb 26, 2021

View reviewed changes

Base automatically changed from master to main March 1, 2021 09:08

jozkee reviewed Mar 2, 2021

View reviewed changes

carlossanlop linked an issue Mar 2, 2021 that may be closed by this pull request

System.IO.Compression: Backport MS Docs documentation to triple slash #48962

Closed

jozkee reviewed Mar 2, 2021

View reviewed changes

jozkee approved these changes Mar 2, 2021

View reviewed changes

sharwell reviewed Mar 2, 2021

View reviewed changes

gewarren reviewed Mar 9, 2021

View reviewed changes

jeffhandley reviewed Apr 18, 2021

View reviewed changes

jeffhandley marked this pull request as draft April 18, 2021 06:36

ghost closed this May 18, 2021

ghost locked as resolved and limited conversation to collaborators Jun 17, 2021

carlossanlop deleted the BackportCompression branch February 7, 2024 06:42

This pull request was closed.

	public DeflateStream(Stream stream, CompressionLevel compressionLevel) : this(stream, compressionLevel, leaveOpen: false)
	// Implies mode = Compress
	public DeflateStream(Stream stream, CompressionLevel compressionLevel) : this(stream, compressionLevel, leaveOpen: false)

	/// <remarks>This enumeration is used with the <see cref="System.IO.Compression.GZipStream" /> and <see cref="System.IO.Compression.DeflateStream" /> classes.</remarks>
	/// <remarks>This enumeration is used with the <see cref="System.IO.Compression.GZipStream"/> and <see cref="System.IO.Compression.DeflateStream"/> classes.</remarks>

	public GZipStream(Stream stream, CompressionLevel compressionLevel) : this(stream, compressionLevel, leaveOpen: false)
	// Implies mode = Compress
	public GZipStream(Stream stream, CompressionLevel compressionLevel) : this(stream, compressionLevel, leaveOpen: false)

Backport System.IO.Compression docs #48841

Backport System.IO.Compression docs #48841

Conversation

carlossanlop commented Feb 26, 2021 • edited Loading

carlossanlop left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jozkee Mar 2, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jozkee Mar 2, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jozkee Mar 2, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jozkee left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ghost commented May 18, 2021

carlossanlop commented Feb 26, 2021 •

edited

Loading

jozkee Mar 2, 2021 •

edited

Loading

jozkee Mar 2, 2021 •

edited

Loading

jozkee Mar 2, 2021 •

edited

Loading