Improve java.util.zip compression level documentation.

The level parameter (constructors, setLevel, etc)
can be [-1..9], but the docs incorrectly stated [-1..8]
and [0..9].

Explain fully what compression level means in the Deflater
class documentation and point everything else to that
canonical source.

Change-Id: I4b76965d88f0fd0f383bb15a5259a5fa5d81f2b1
Signed-off-by: Jorrit Jongma <jorrit@jongma.org>

2 files changed, 32 insertions, 31 deletions

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 @@ import libcore.util.EmptyArray;
  * {@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 class Deflater {
     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 @@ public class Deflater {
     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 @@ public class Deflater {
     }
 
     /**
-     * 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 @@ public class Deflater {
     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 @@ public class ZipOutputStream extends DeflaterOutputStream implements ZipConstant
     }
 
     /**
-     * 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) {