Merge "Improve java.util.zip compression level documentation."
diff --git a/luni/src/main/java/java/util/zip/Deflater.java b/luni/src/main/java/java/util/zip/Deflater.java
index 1593a60..d96ab2a 100644
--- a/luni/src/main/java/java/util/zip/Deflater.java
+++ b/luni/src/main/java/java/util/zip/Deflater.java
@@ -50,21 +50,37 @@
* {@link #setInput setInput} repeatedly, but you're much better off using
* {@link DeflaterOutputStream} to handle all this for you. {@link DeflaterOutputStream} also helps
* minimize memory requirements — the sample code above is very expensive.
+ *
+ * <a name="compression_level"><h3>Compression levels</h3></a>
+ * <p>A compression level must be {@link #DEFAULT_COMPRESSION} to compromise between speed and
+ * compression (currently equivalent to level 6), or between 0 ({@link #NO_COMPRESSION}, where
+ * the input is simply copied) and 9 ({@link #BEST_COMPRESSION}). Level 1 ({@link #BEST_SPEED})
+ * performs some compression, but with minimal speed overhead.
*/
public class Deflater {
/**
- * Upper bound for the compression level range.
+ * This <a href="#compression_level">compression level</a> gives the best compression,
+ * but takes the most time.
*/
public static final int BEST_COMPRESSION = 9;
/**
- * Lower bound for compression level range.
+ * This <a href="#compression_level">compression level</a> gives minimal compression,
+ * but takes the least time (of any level that actually performs compression;
+ * see {@link #NO_COMPRESSION}).
*/
public static final int BEST_SPEED = 1;
/**
- * The default compression level.
+ * This <a href="#compression_level">compression level</a> does no compression.
+ * It is even faster than {@link #BEST_SPEED}.
+ */
+ public static final int NO_COMPRESSION = 0;
+
+ /**
+ * The default <a href="#compression_level">compression level</a>.
+ * This is a trade-off between speed and compression, currently equivalent to level 6.
*/
public static final int DEFAULT_COMPRESSION = -1;
@@ -89,11 +105,6 @@
public static final int HUFFMAN_ONLY = 2;
/**
- * A compression level.
- */
- public static final int NO_COMPRESSION = 0;
-
- /**
* Use buffering for best compression.
*
* @hide
@@ -150,8 +161,9 @@
private final CloseGuard guard = CloseGuard.get();
/**
- * Constructs a new {@code Deflater} instance using the default compression
- * level. The strategy can be specified with {@link #setStrategy}. A
+ * Constructs a new {@code Deflater} instance using the
+ * default <a href="#compression_level">compression level</a>.
+ * The compression strategy can be specified with {@link #setStrategy}. A
* header is added to the output by default; use {@link
* #Deflater(int, boolean)} if you need to omit the header.
*/
@@ -160,28 +172,22 @@
}
/**
- * Constructs a new {@code Deflater} instance using compression
- * level {@code level}. The strategy can be specified with {@link #setStrategy}.
+ * Constructs a new {@code Deflater} instance with the
+ * given <a href="#compression_level">compression level</a>.
+ * The compression strategy can be specified with {@link #setStrategy}.
* A header is added to the output by default; use
* {@link #Deflater(int, boolean)} if you need to omit the header.
- *
- * @param level
- * the compression level in the range between 0 and 9.
*/
public Deflater(int level) {
this(level, false);
}
/**
- * Constructs a new {@code Deflater} instance with a specific compression
- * level. If {@code noHeader} is true, no ZLIB header is added to the
+ * Constructs a new {@code Deflater} instance with the
+ * given <a href="#compression_level">compression level</a>.
+ * If {@code noHeader} is true, no ZLIB header is added to the
* output. In a zip file, every entry (compressed file) comes with such a
* header. The strategy can be specified using {@link #setStrategy}.
- *
- * @param level
- * the compression level in the range between 0 and 9.
- * @param noHeader
- * {@code true} indicates that no ZLIB header should be written.
*/
public Deflater(int level, boolean noHeader) {
if (level < DEFAULT_COMPRESSION || level > BEST_COMPRESSION) {
@@ -414,8 +420,8 @@
private native void setInputImpl(byte[] buf, int offset, int byteCount, long handle);
/**
- * Sets the compression level to be used when compressing data. The
- * compression level must be a value between 0 and 9. This value must be set
+ * Sets the given <a href="#compression_level">compression level</a>
+ * to be used when compressing data. This value must be set
* prior to calling {@link #setInput setInput}.
* @exception IllegalArgumentException
* If the compression level is invalid.
diff --git a/luni/src/main/java/java/util/zip/ZipOutputStream.java b/luni/src/main/java/java/util/zip/ZipOutputStream.java
index 5db2262..59849d3 100644
--- a/luni/src/main/java/java/util/zip/ZipOutputStream.java
+++ b/luni/src/main/java/java/util/zip/ZipOutputStream.java
@@ -361,13 +361,8 @@
}
/**
- * Sets the compression level to be used for writing entry data. This level
- * may be set on a per entry basis. The level must have a value between -1
- * and 8 according to the {@code Deflater} compression level bounds.
- *
- * @param level
- * the compression level (ranging from -1 to 8).
- * @see Deflater
+ * Sets the <a href="Deflater.html#compression_level">compression level</a> to be used
+ * for writing entry data.
*/
public void setLevel(int level) {
if (level < Deflater.DEFAULT_COMPRESSION || level > Deflater.BEST_COMPRESSION) {
