Backport System.IO.Compression docs

src/libraries/System.IO.Compression/src/System.IO.Compression.csproj

@@ -1,8 +1,9 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
     <TargetFrameworks>$(NetCoreAppCurrent)-windows;$(NetCoreAppCurrent)-Unix;$(NetCoreAppCurrent)-Browser</TargetFrameworks>
     <Nullable>enable</Nullable>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
   <ItemGroup>
     <Compile Include="$(CommonPath)Interop\Interop.zlib.cs" />

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

@@ -3,27 +3,19 @@
 
 namespace System.IO.Compression
 {
-    /// <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>
+    /// <remarks><format type="text/markdown"><![CDATA[
+    /// [!INCLUDE[remarks](~/includes/remarks/System.IO.Compression/CompressionLevel/CompressionLevel.md)]
+    /// ]]></format></remarks>
     public enum CompressionLevel
     {
-        /// <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>
         Optimal = 0,
 
-        /// <summary>
-        /// The compression operation should complete as quickly as possible, even if the resulting file is not optimally compressed.
-        /// </summary>
+        /// <summary>The compression operation should complete as quickly as possible, even if the resulting file is not optimally compressed.</summary>
         Fastest = 1,
 
-        /// <summary>
-        /// No compression should be performed on the file.
-        /// </summary>
+        /// <summary>No compression should be performed on the file.</summary>
         NoCompression = 2,
 
         /// <summary>

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>
+    /// <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)]
+    /// [!code-vb[IO.Compression.GZip1#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.Compression.GZip1/VB/gziptest.vb#1)]
+    /// ]]></format></example>
     public enum CompressionMode
     {
+        /// <summary>Decompresses the underlying stream.</summary>
         Decompress = 0,
+        /// <summary>Compresses the underlying stream.</summary>
         Compress = 1
     }
 }

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

@@ -3,6 +3,10 @@
 
 namespace System.IO.Compression
 {
+    /// <summary>Represents a compressed file within a zip archive.</summary>
+    /// <remarks><format type="text/markdown"><![CDATA[
+    /// [!INCLUDE[remarks](~/includes/remarks/System.IO.Compression/ZipArchiveEntry/ZipArchiveEntry.md)]
+    /// ]]></format></remarks>
     public partial class ZipArchiveEntry
     {
         internal const ZipVersionMadeByPlatform CurrentZipPlatform = ZipVersionMadeByPlatform.Windows;

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

@@ -8,7 +8,10 @@
 
 namespace System.IO.Compression
 {
-    // The disposable fields that this class owns get disposed when the ZipArchive it belongs to gets disposed
+    /// <summary>Represents a compressed file within a zip archive.</summary>
+    /// <remarks><format type="text/markdown"><![CDATA[
+    /// [!INCLUDE[remarks](~/includes/remarks/System.IO.Compression/ZipArchiveEntry/ZipArchiveEntry.md)]
+    /// ]]></format></remarks>
     public partial class ZipArchiveEntry
     {
         // The maximum index of our buffers, from the maximum index of a byte array
@@ -139,18 +142,24 @@ internal ZipArchiveEntry(ZipArchive archive, string entryName)
             }
         }
 
-        /// <summary>
-        /// The ZipArchive that this entry belongs to. If this entry has been deleted, this will return null.
-        /// </summary>
+        /// <summary>Gets the zip archive that the entry belongs to.</summary>
+        /// <value>The zip archive that the entry belongs to, or <see langword="null" /> if the entry has been deleted.</value>
         public ZipArchive Archive => _archive;
 
+        /// <summary>The 32-bit Cyclic Redundant Check.</summary>
+        /// <value>An unsigned integer (4 bytes) representing the CRC-32 field.</value>
         [CLSCompliant(false)]
         public uint Crc32 => _crc32;
 
-        /// <summary>
-        /// The compressed size of the entry. If the archive that the entry belongs to is in Create mode, attempts to get this property will always throw an exception. If the archive that the entry belongs to is in update mode, this property will only be valid if the entry has not been opened.
-        /// </summary>
-        /// <exception cref="InvalidOperationException">This property is not available because the entry has been written to or modified.</exception>
+        /// <summary>Gets the compressed size of the entry in the zip archive.</summary>
+        /// <value>The compressed size of the entry in the zip archive.</value>
+        /// <remarks>This property cannot be retrieved when the mode is set to <see cref="System.IO.Compression.ZipArchiveMode.Create" />, or the mode is set to <see cref="System.IO.Compression.ZipArchiveMode.Update" /> and the entry has been opened.</remarks>
+        /// <example>The following example shows how to retrieve entries in a zip archive, and evaluate the properties of the entries. It uses the <see cref="System.IO.Compression.ZipArchiveEntry.Name" /> property to display the name of the entry, and the <see cref="System.IO.Compression.ZipArchiveEntry.Length" /> and <see cref="System.IO.Compression.ZipArchiveEntry.CompressedLength" /> properties to calculate how much the file was compressed.
+        /// <format type="text/markdown"><![CDATA[
+        /// [!code-csharp[System.IO.Compression.ZipArchiveEntry#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchiveentry/cs/program1.cs#1)]
+        /// [!code-vb[System.IO.Compression.ZipArchiveEntry#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchiveentry/vb/program1.vb#1)]
+        /// ]]></format></example>
+        /// <exception cref="System.InvalidOperationException">The value of the property is not available because the entry has been modified.</exception>
         public long CompressedLength
         {
             get
@@ -161,6 +170,9 @@ public long CompressedLength
             }
         }
 
+        /// <summary>OS and application specific file attributes.</summary>
+        /// <value>The external attributes written by the application when this entry was written. It is both host OS and application dependent.</value>
+        /// <remarks>The mapping of the external attributes is host-system dependent. For MS-DOS, the low order byte is the MS-DOS directory attribute byte. For Unix, the high Order byte is frequently used to store the file permissions. If input came from standard input, this field is set to zero.</remarks>
         public int ExternalAttributes
         {
             get
@@ -174,9 +186,11 @@ public int ExternalAttributes
             }
         }
 
-        /// <summary>
-        /// The relative path of the entry as stored in the Zip archive. Note that Zip archives allow any string to be the path of the entry, including invalid and absolute paths.
-        /// </summary>
+        /// <summary>Gets the relative path of the entry in the zip archive.</summary>
+        /// <value>The relative path of the entry in the zip archive.</value>
+        /// <remarks><format type="text/markdown"><![CDATA[
+        /// [!INCLUDE[remarks](~/includes/remarks/System.IO.Compression/ZipArchiveEntry/FullName.md)]
+        /// ]]></format></remarks>
         public string FullName
         {
             get
@@ -205,16 +219,16 @@ private set
             }
         }
 
-        /// <summary>
-        /// The last write time of the entry as stored in the Zip archive. When setting this property, the DateTime will be converted to the
-        /// Zip timestamp format, which supports a resolution of two seconds. If the data in the last write time field is not a valid Zip timestamp,
-        /// an indicator value of 1980 January 1 at midnight will be returned.
-        /// </summary>
-        /// <exception cref="NotSupportedException">An attempt to set this property was made, but the ZipArchive that this entry belongs to was
-        /// opened in read-only mode.</exception>
-        /// <exception cref="ArgumentOutOfRangeException">An attempt was made to set this property to a value that cannot be represented in the
-        /// Zip timestamp format. The earliest date/time that can be represented is 1980 January 1 0:00:00 (midnight), and the last date/time
-        /// that can be represented is 2107 December 31 23:59:58 (one second before midnight).</exception>
+        /// <summary>Gets or sets the last time the entry in the zip archive was changed.</summary>
+        /// <value>The last time the entry in the zip archive was changed.</value>
+        /// <remarks><format type="text/markdown"><![CDATA[
+        /// [!INCLUDE[remarks](~/includes/remarks/System.IO.Compression/ZipArchiveEntry/LastWriteTime.md)]
+        /// ]]></format></remarks>
+        /// <exception cref="System.NotSupportedException">The attempt to set this property failed, because the zip archive for the entry is in <see cref="System.IO.Compression.ZipArchiveMode.Read" /> mode.</exception>
+        /// <exception cref="System.IO.IOException">The archive mode is set to <see cref="System.IO.Compression.ZipArchiveMode.Create" />.
+        /// -or-
+        /// The archive mode is set to <see cref="System.IO.Compression.ZipArchiveMode.Update" /> and the entry has been opened.</exception>
+        /// <exception cref="System.ArgumentOutOfRangeException">An attempt was made to set this property to a value that is either earlier than 1980 January 1 0:00:00 (midnight) or later than 2107 December 31 23:59:58 (one second before midnight).</exception>
         public DateTimeOffset LastWriteTime
         {
             get
@@ -235,10 +249,15 @@ public DateTimeOffset LastWriteTime
             }
         }
 
-        /// <summary>
-        /// The uncompressed size of the entry. This property is not valid in Create mode, and it is only valid in Update mode if the entry has not been opened.
-        /// </summary>
-        /// <exception cref="InvalidOperationException">This property is not available because the entry has been written to or modified.</exception>
+        /// <summary>Gets the uncompressed size of the entry in the zip archive.</summary>
+        /// <value>The uncompressed size of the entry in the zip archive.</value>
+        /// <remarks>This property cannot be retrieved when the mode is set to <see cref="System.IO.Compression.ZipArchiveMode.Create" />, or the mode is set to <see cref="System.IO.Compression.ZipArchiveMode.Update" /> and the entry has been opened.</remarks>
+        /// <example>The following example shows how to retrieve entries from a zip archive, and evaluate the properties of the entries. It uses the <see cref="System.IO.Compression.ZipArchiveEntry.Name" /> property to display the name of the entry, and the <see cref="System.IO.Compression.ZipArchiveEntry.Length" /> and <see cref="System.IO.Compression.ZipArchiveEntry.CompressedLength" /> properties to calculate how much the file was compressed.
+        /// <format type="text/markdown"><![CDATA[
+        /// [!code-csharp[System.IO.Compression.ZipArchiveEntry#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchiveentry/cs/program1.cs#1)]
+        /// [!code-vb[System.IO.Compression.ZipArchiveEntry#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchiveentry/vb/program1.vb#1)]
+        /// ]]></format></example>
+        /// <exception cref="System.InvalidOperationException">The value of the property is not available because the entry has been modified.</exception>
         public long Length
         {
             get
@@ -249,17 +268,17 @@ public long Length
             }
         }
 
-        /// <summary>
-        /// The filename of the entry. This is equivalent to the substring of Fullname that follows the final directory separator character.
-        /// </summary>
+        /// <summary>Gets the file name of the entry in the zip archive.</summary>
+        /// <value>The file name of the entry in the zip archive.</value>
+        /// <remarks><format type="text/markdown"><![CDATA[
+        /// [!INCLUDE[remarks](~/includes/remarks/System.IO.Compression/ZipArchiveEntry/Name.md)]
+        /// ]]></format></remarks>
         public string Name => ParseFileName(FullName, _versionMadeByPlatform);
 
-        /// <summary>
-        /// Deletes the entry from the archive.
-        /// </summary>
-        /// <exception cref="IOException">The entry is already open for reading or writing.</exception>
-        /// <exception cref="NotSupportedException">The ZipArchive that this entry belongs to was opened in a mode other than ZipArchiveMode.Update. </exception>
-        /// <exception cref="ObjectDisposedException">The ZipArchive that this entry belongs to has been disposed.</exception>
+        /// <summary>Deletes the entry from the zip archive.</summary>
+        /// <exception cref="System.IO.IOException">The entry is already open for reading or writing.</exception>
+        /// <exception cref="System.NotSupportedException">The zip archive for this entry was opened in a mode other than <see cref="System.IO.Compression.ZipArchiveMode.Update" />.</exception>
+        /// <exception cref="System.ObjectDisposedException">The zip archive for this entry has been disposed.</exception>
         public void Delete()
         {
             if (_archive == null)
@@ -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.
-        /// </summary>
-        /// <returns>A Stream that represents the contents of the entry.</returns>
-        /// <exception cref="IOException">The entry is already currently open for writing. -or- The entry has been deleted from the archive. -or- The archive that this entry belongs to was opened in ZipArchiveMode.Create, and this entry has already been written to once.</exception>
-        /// <exception cref="InvalidDataException">The entry is missing from the archive or is corrupt and cannot be read. -or- The entry has been compressed using a compression method that is not supported.</exception>
-        /// <exception cref="ObjectDisposedException">The ZipArchive that this entry belongs to has been disposed.</exception>
+        /// <summary>Opens the entry from the zip archive.</summary>
+        /// <returns>The stream that represents the contents of the entry.</returns>
+        /// <remarks>You use this method to access the stream for an entry in a zip archive. After retrieving the stream, you can read from or write to the stream. When you write to the stream, the modifications you make to the entry will appear in the zip archive.</remarks>
+        /// <example>The following example shows how to create a new entry, open it with the <see cref="System.IO.Compression.ZipArchiveEntry.Open" /> method, and write to the stream.
+        /// <format type="text/markdown"><![CDATA[
+        /// [!code-csharp[System.IO.Compression.ZipArchiveMode#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchivemode/cs/program1.cs#1)]
+        /// [!code-vb[System.IO.Compression.ZipArchiveMode#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchivemode/vb/program1.vb#1)]
+        /// ]]></format></example>
+        /// <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.ObjectDisposedException">The zip archive for this entry has been disposed.</exception>
         public Stream Open()
         {
             ThrowIfInvalidArchive();
@@ -302,10 +331,8 @@ public Stream Open()
             }
         }
 
-        /// <summary>
-        /// Returns the FullName of the entry.
-        /// </summary>
-        /// <returns>FullName of the entry</returns>
+        /// <summary>Retrieves the relative path of the entry in the zip archive.</summary>
+        /// <returns>The relative path of the entry, which is the value stored in the <see cref="System.IO.Compression.ZipArchiveEntry.FullName" /> property.</returns>
         public override string ToString()
         {
             return FullName;

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

@@ -3,29 +3,17 @@
 
 namespace System.IO.Compression
 {
+    /// <summary>Specifies values for interacting with zip archive entries.</summary>
+    /// <remarks><format type="text/markdown"><![CDATA[
+    /// [!INCLUDE[remarks](~/includes/remarks/System.IO.Compression/ZipArchiveMode/ZipArchiveMode.md)]
+    /// ]]></format></remarks>
     public enum ZipArchiveMode
     {
-        /// <summary>
-        /// Only reading entries from the archive is permitted.
-        /// If the underlying file or stream is seekable, then files will be read from the archive on-demand as they are requested.
-        /// If the underlying file or stream is not seekable, the entire archive will be held in memory.
-        /// Requires that the underlying file or stream is readable.
-        /// </summary>
+        /// <summary>Only reading archive entries is permitted.</summary>
         Read,
-        /// <summary>
-        /// Only supports the creation of new archives.
-        /// Only writing to newly created entries in the archive is permitted.
-        /// Each entry in the archive can only be opened for writing once.
-        /// If only one entry is written to at a time, data will be written to the underlying stream or file as soon as it is available.
-        /// The underlying stream must be writable, but need not be seekable.
-        /// </summary>
+        /// <summary>Only creating new archive entries is permitted.</summary>
         Create,
-        /// <summary>
-        /// Reading and writing from entries in the archive is permitted.
-        /// Requires that the contents of the entire archive be held in memory.
-        /// The underlying file or stream must be readable, writable and seekable.
-        /// No data will be written to the underlying file or stream until the archive is disposed.
-        /// </summary>
+        /// <summary>Both read and write operations are permitted for archive entries.</summary>
         Update
     }
 }