@@ -10,8 +10,9 @@ namespace System.IO.Compression
1010 /// This class provides declaration for constants and PInvokes as well as some basic tools for exposing the
1111 /// native System.IO.Compression.Native.dll (effectively, ZLib) library to managed code.
1212 ///
13- /// See also: How to choose a compression level (in comments to <code> CompressionLevel</code>.
13+ /// <para> See also: How to choose a compression level (in comments to <see cref=" CompressionLevel" />.)</para>
1414 /// </summary>
15+ /// <seealso href="https://www.zlib.net/manual.html">ZLib manual</seealso>
1516 internal static partial class ZLibNative
1617 {
1718 // This is the NULL pointer for using with ZLib pointers;
@@ -38,21 +39,22 @@ public enum ErrorCode : int
3839 }
3940
4041 /// <summary>
41- /// <p ><strong>From the ZLib manual:</strong></p >
42- /// <p><code> CompressionStrategy</code > is used to tune the compression algorithm.<br />
43- /// Use the value <code> DefaultStrategy</code > for normal data, <code> Filtered</code > for data produced by a filter (or predictor),
44- /// <code> HuffmanOnly</code > to force Huffman encoding only (no string match), or <code>Rle</code > to limit match distances to one
42+ /// <para ><strong>From the ZLib manual:</strong><br / >
43+ /// <see cref=" CompressionStrategy" / > is used to tune the compression algorithm.<br />
44+ /// Use the value <see cref=" DefaultStrategy" / > for normal data, <see cref=" Filtered" / > for data produced by a filter (or predictor),
45+ /// <see cref=" HuffmanOnly" / > to force Huffman encoding only (no string match), or <see cref="RunLengthEncoding" / > to limit match distances to one
4546 /// (run-length encoding). Filtered data consists mostly of small values with a somewhat random distribution. In this case, the
46- /// compression algorithm is tuned to compress them better. The effect of <code> Filtered</code > is to force more Huffman coding and]
47- /// less string matching; it is somewhat intermediate between <code> DefaultStrategy</code > and <code> HuffmanOnly</code >.
48- /// <code>Rle</code > is designed to be almost as fast as <code> HuffmanOnly</code >, but give better compression for PNG image data.
47+ /// compression algorithm is tuned to compress them better. The effect of <see cref=" Filtered" / > is to force more Huffman coding and
48+ /// less string matching; it is somewhat intermediate between <see cref=" DefaultStrategy" / > and <see cref=" HuffmanOnly" / >.
49+ /// <see cref="RunLengthEncoding" / > is designed to be almost as fast as <see cref=" HuffmanOnly" / >, but give better compression for PNG image data.
4950 /// The strategy parameter only affects the compression ratio but not the correctness of the compressed output even if it is not set
50- /// appropriately. <code> Fixed</code > prevents the use of dynamic Huffman codes, allowing for a simpler decoder for special applications.</p >
51+ /// appropriately. <see cref=" Fixed" / > prevents the use of dynamic Huffman codes, allowing for a simpler decoder for special applications.</para >
5152 ///
52- /// <p><strong>For .NET Framework use:</strong></p>
53- /// <p>We have investigated compression scenarios for a bunch of different frequently occurring compression data and found that in all
54- /// cases we investigated so far, <code>DefaultStrategy</code> provided best results</p>
55- /// <p>See also: How to choose a compression level (in comments to <code>CompressionLevel</code>.</p>
53+ /// <para><strong>For .NET Framework use:</strong><br />
54+ /// We have investigated compression scenarios for a bunch of different frequently occurring compression data and found that in all
55+ /// cases we investigated so far, <see cref="DefaultStrategy" /> provided best results</para>
56+ ///
57+ /// <para>See also: How to choose a compression level (in comments to <see cref="CompressionLevel" />.)</para>
5658 /// </summary>
5759 public enum CompressionStrategy : int
5860 {
@@ -64,51 +66,53 @@ public enum CompressionStrategy : int
6466 }
6567
6668 /// <summary>
67- /// In version 1 .2.3, ZLib provides on the <code> Deflated</code>-<code> CompressionMethod</code >.
69+ /// In version 2 .2.1, zlib-ng provides only the <see cref=" Deflated" /> <see cref=" CompressionMethod" / >.
6870 /// </summary>
6971 public enum CompressionMethod : int
7072 {
7173 Deflated = 8
7274 }
7375
7476 /// <summary>
75- /// <p ><strong>From the ZLib manual:</strong></p >
76- /// <p> ZLib's <code >windowBits</code > parameter is the base two logarithm of the window size (the size of the history buffer).
77+ /// <para ><strong>From the ZLib manual:</strong><br / >
78+ /// ZLib's <c >windowBits</c > parameter is the base two logarithm of the window size (the size of the history buffer).
7779 /// It should be in the range 8..15 for this version of the library. Larger values of this parameter result in better compression
78- /// at the expense of memory usage. The default value is 15 if deflateInit is used instead.<br /></p>
79- /// <strong>Note</strong>:
80- /// <code>windowBits</code> can also be -8..-15 for raw deflate. In this case, -windowBits determines the window size.
81- /// <code>Deflate</code> will then generate raw deflate data with no ZLib header or trailer, and will not compute an adler32 check value.<br />
82- /// <p>See also: How to choose a compression level (in comments to <code>CompressionLevel</code>.</p>
80+ /// at the expense of memory usage. The default value is 15 if <c>deflateInit</c> is used instead.</para>
81+ ///
82+ /// <para><strong>Note</strong>: <c>windowBits</c> can also be -8..-15 for raw deflate. In this case, -windowBits determines the window size.
83+ /// <c>Deflate</c> will then generate raw deflate data with no ZLib header or trailer, and will not compute an adler32 check value.</para>
84+ ///
85+ /// <para>See also: How to choose a compression level (in comments to <see cref="CompressionLevel" />.)</para>
8386 /// </summary>
8487 public const int Deflate_DefaultWindowBits = - 15 ; // Legal values are 8..15 and -8..-15. 15 is the window size,
8588 // negative val causes deflate to produce raw deflate data (no zlib header).
8689
8790 /// <summary>
88- /// <p ><strong>From the ZLib manual:</strong></p >
89- /// <p> ZLib's <code >windowBits</code > parameter is the base two logarithm of the window size (the size of the history buffer).
91+ /// <para ><strong>From the ZLib manual:</strong><br / >
92+ /// ZLib's <c >windowBits</c > parameter is the base two logarithm of the window size (the size of the history buffer).
9093 /// It should be in the range 8..15 for this version of the library. Larger values of this parameter result in better compression
91- /// at the expense of memory usage. The default value is 15 if deflateInit is used instead.<br /></p >
94+ /// at the expense of memory usage. The default value is 15 if <c> deflateInit</c> is used instead.</para >
9295 /// </summary>
9396 public const int ZLib_DefaultWindowBits = 15 ;
9497
9598 /// <summary>
96- /// <p>Zlib 's <code >windowBits</code > parameter is the base two logarithm of the window size (the size of the history buffer).
97- /// For GZip header encoding, <code >windowBits</code > should be equal to a value between 8..15 (to specify Window Size) added to
98- /// 16. The range of values for GZip encoding is therefore 24..31.
99- /// <strong>Note</strong>:
99+ /// <para>ZLib 's <c >windowBits</c > parameter is the base two logarithm of the window size (the size of the history buffer).
100+ /// For GZip header encoding, <c >windowBits</c > should be equal to a value between 8..15 (to specify Window Size) added to
101+ /// 16. The range of values for GZip encoding is therefore 24..31.</para>
102+ /// <para>< strong>Note</strong>:<br />
100103 /// The GZip header will have no file name, no extra data, no comment, no modification time (set to zero), no header crc, and
101- /// the operating system will be set based on the OS that the ZLib library was compiled to. <code >ZStream.adler</code >
102- /// is a crc32 instead of an adler32.</p >
104+ /// the operating system will be set based on the OS that the ZLib library was compiled to. <c >ZStream.adler</c >
105+ /// is a crc32 instead of an adler32.</para >
103106 /// </summary>
104107 public const int GZip_DefaultWindowBits = 31 ;
105108
106109 /// <summary>
107- /// <p><strong>From the ZLib manual:</strong></p>
108- /// <p>The <code>memLevel</code> parameter specifies how much memory should be allocated for the internal compression state.
109- /// <code>memLevel</code> = 1 uses minimum memory but is slow and reduces compression ratio; <code>memLevel</code> = 9 uses maximum
110- /// memory for optimal speed. The default value is 8.</p>
111- /// <p>See also: How to choose a compression level (in comments to <code>CompressionLevel</code>.</p>
110+ /// <para><strong>From the ZLib manual:</strong><br />
111+ /// The <c>memLevel</c> parameter specifies how much memory should be allocated for the internal compression state.
112+ /// <c>memLevel</c> = 1 uses minimum memory but is slow and reduces compression ratio; <c>memLevel</c> = 9 uses maximum
113+ /// memory for optimal speed. The default value is 8.</para>
114+ ///
115+ /// <para>See also: How to choose a compression level (in comments to <see cref="CompressionLevel" />.)</para>
112116 /// </summary>
113117 public const int Deflate_DefaultMemLevel = 8 ; // Memory usage by deflate. Legal range: [1..9]. 8 is ZLib default.
114118 // More is faster and better compression with more memory usage.
@@ -118,16 +122,16 @@ public enum CompressionMethod : int
118122 public const byte GZip_Header_ID2 = 139 ;
119123
120124 /**
121- * Do not remove the nested typing of types inside of <code>System.IO.Compression. ZLibNative</code >.
125+ * Do not remove the nested typing of types inside of <see cref=" ZLibNative" / >.
122126 * This was done on purpose to:
123127 *
124- * - Achieve the right encapsulation in a situation where <code> ZLibNative</code > may be compiled division-wide
125- * into different assemblies that wish to consume <code >System.IO.Compression.Native</code >. Since <code >internal</code >
126- * scope is effectively like <code >public</code > scope when compiling <code> ZLibNative</code > into a higher
127- * level assembly, we need a combination of inner types and <code >private</code >-scope members to achieve
128+ * - Achieve the right encapsulation in a situation where <see cref=" ZLibNative" / > may be compiled division-wide
129+ * into different assemblies that wish to consume <c >System.IO.Compression.Native</c >. Since <c >internal</c >
130+ * scope is effectively like <c >public</c > scope when compiling <see cref=" ZLibNative" / > into a higher
131+ * level assembly, we need a combination of inner types and <c >private</c >-scope members to achieve
128132 * the right encapsulation.
129133 *
130- * - Achieve late dynamic loading of <code >System.IO.Compression.Native.dll</code > at the right time.
134+ * - Achieve late dynamic loading of <c >System.IO.Compression.Native.dll</c > at the right time.
131135 * The native assembly will not be loaded unless it is actually used since the loading is performed by a static
132136 * constructor of an inner type that is not directly referenced by user code.
133137 *
@@ -137,15 +141,15 @@ public enum CompressionMethod : int
137141 */
138142
139143 /// <summary>
140- /// The <code> ZLibStreamHandle</code > could be a <code> CriticalFinalizerObject</code > rather than a
141- /// <code>SafeHandleMinusOneIsInvalid</code >. This would save an <code> IntPtr</code > field since
142- /// <code> ZLibStreamHandle</code > does not actually use its <code> handle</code > field.
143- /// Instead it uses a <code> private ZStream zStream</code > field which is the actual handle data
144+ /// The <see cref=" ZLibStreamHandle" / > could be a <see cref="System.Runtime.ConstrainedExecution. CriticalFinalizerObject" / > rather than a
145+ /// <see cref="SafeHandle" / >. This would save an <see cref=" IntPtr" / > field since
146+ /// <see cref=" ZLibStreamHandle" / > does not actually use its <see cref="SafeHandle. handle" / > field.
147+ /// Instead it uses a private <see cref="_zStream" / > field which is the actual handle data
144148 /// structure requiring critical finalization.
145149 /// However, we would like to take advantage if the better debugability offered by the fact that a
146- /// <em>releaseHandleFailed MDA</em> is raised if the <code> ReleaseHandle</code > method returns
147- /// <code >false</code >, which can for instance happen if the underlying ZLib <code>XxxxEnd</code >
148- /// routines return an failure error code.
150+ /// <em>releaseHandleFailed MDA</em> is raised if the <see cref=" ReleaseHandle" / > method returns
151+ /// <c >false</c >, which can for instance happen if the underlying ZLib <see cref="Interop.ZLib.InflateEnd"/ >
152+ /// or <see cref="Interop.ZLib.DeflateEnd"/> routines return an failure error code.
149153 /// </summary>
150154 public sealed class ZLibStreamHandle : SafeHandle
151155 {
0 commit comments