compress/flate: document HuffmanOnly

Fixes #16489

Change-Id: I13e2ed6de59102f977566de637d8d09b4e541980
Reviewed-on: https://go-review.googlesource.com/25200
Reviewed-by: Andrew Gerrand <adg@golang.org>
Run-TryBot: Joe Tsai <thebrokentoaster@gmail.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>

diff --git a/src/compress/flate/deflate.go b/src/compress/flate/deflate.go
index 8a085ba34740f9ed9152615dad3e339b30f9bd0b..3e4dc7b57e1e052233407b5200335f1729fc9c92 100644 (file)
--- a/src/compress/flate/deflate.go
+++ b/src/compress/flate/deflate.go
@@ -15,7 +15,17 @@ const (
        BestSpeed          = 1
        BestCompression    = 9
        DefaultCompression = -1
-       HuffmanOnly        = -2 // Disables match search and only does Huffman entropy reduction.
+
+       // HuffmanOnly disables Lempel-Ziv match searching and only performs Huffman
+       // entropy encoding. This mode is useful in compressing data that has
+       // already been compressed with an LZ style algorithm (e.g. Snappy or LZ4)
+       // that lacks an entropy encoder. Compression gains are achieved when
+       // certain bytes in the input stream occur more frequently than others.
+       //
+       // Note that HuffmanOnly produces a compressed output that is
+       // RFC 1951 compliant. That is, any valid DEFLATE decompressor will
+       // continue to be able to decompress this output.
+       HuffmanOnly = -2
 )
 
 const (
@@ -644,7 +654,6 @@ func (d *compressor) close() error {
 // a very fast compression for all types of input, but sacrificing considerable
 // compression efficiency.
 //
-//
 // If level is in the range [-2, 9] then the error returned will be nil.
 // Otherwise the error returned will be non-nil.
 func NewWriter(w io.Writer, level int) (*Writer, error) {