Skip to content

Commit e4f72f7

Browse files
cuishuanggopherbot
authored andcommitted
compress: add available godoc link
Change-Id: Ia6e88aec59cb294e8b303a00fcd69f4cbf0dc09a Reviewed-on: https://go-review.googlesource.com/c/go/+/534759 Reviewed-by: Ian Lance Taylor <[email protected]> Reviewed-by: Dmitri Shuralyov <[email protected]> TryBot-Result: Gopher Robot <[email protected]> Auto-Submit: Ian Lance Taylor <[email protected]> Run-TryBot: shuang cui <[email protected]>
1 parent ade730a commit e4f72f7

File tree

8 files changed

+75
-75
lines changed

8 files changed

+75
-75
lines changed

src/compress/bzip2/bit_reader.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ func newBitReader(r io.Reader) bitReader {
3232

3333
// ReadBits64 reads the given number of bits and returns them in the
3434
// least-significant part of a uint64. In the event of an error, it returns 0
35-
// and the error can be obtained by calling Err().
35+
// and the error can be obtained by calling [bitReader.Err]().
3636
func (br *bitReader) ReadBits64(bits uint) (n uint64) {
3737
for bits > br.bits {
3838
b, err := br.r.ReadByte()

src/compress/flate/deflate.go

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -650,13 +650,13 @@ func (d *compressor) close() error {
650650
return nil
651651
}
652652

653-
// NewWriter returns a new Writer compressing data at the given level.
654-
// Following zlib, levels range from 1 (BestSpeed) to 9 (BestCompression);
653+
// NewWriter returns a new [Writer] compressing data at the given level.
654+
// Following zlib, levels range from 1 ([BestSpeed]) to 9 ([BestCompression]);
655655
// higher levels typically run slower but compress more. Level 0
656-
// (NoCompression) does not attempt any compression; it only adds the
656+
// ([NoCompression]) does not attempt any compression; it only adds the
657657
// necessary DEFLATE framing.
658-
// Level -1 (DefaultCompression) uses the default compression level.
659-
// Level -2 (HuffmanOnly) will use Huffman compression only, giving
658+
// Level -1 ([DefaultCompression]) uses the default compression level.
659+
// Level -2 ([HuffmanOnly]) will use Huffman compression only, giving
660660
// a very fast compression for all types of input, but sacrificing considerable
661661
// compression efficiency.
662662
//
@@ -670,11 +670,11 @@ func NewWriter(w io.Writer, level int) (*Writer, error) {
670670
return &dw, nil
671671
}
672672

673-
// NewWriterDict is like NewWriter but initializes the new
674-
// Writer with a preset dictionary. The returned Writer behaves
673+
// NewWriterDict is like [NewWriter] but initializes the new
674+
// [Writer] with a preset dictionary. The returned [Writer] behaves
675675
// as if the dictionary had been written to it without producing
676676
// any compressed output. The compressed data written to w
677-
// can only be decompressed by a Reader initialized with the
677+
// can only be decompressed by a [Reader] initialized with the
678678
// same dictionary.
679679
func NewWriterDict(w io.Writer, level int, dict []byte) (*Writer, error) {
680680
dw := &dictWriter{w}
@@ -698,7 +698,7 @@ func (w *dictWriter) Write(b []byte) (n int, err error) {
698698
var errWriterClosed = errors.New("flate: closed writer")
699699

700700
// A Writer takes data written to it and writes the compressed
701-
// form of that data to an underlying writer (see NewWriter).
701+
// form of that data to an underlying writer (see [NewWriter]).
702702
type Writer struct {
703703
d compressor
704704
dict []byte
@@ -714,7 +714,7 @@ func (w *Writer) Write(data []byte) (n int, err error) {
714714
// It is useful mainly in compressed network protocols, to ensure that
715715
// a remote reader has enough data to reconstruct a packet.
716716
// Flush does not return until the data has been written.
717-
// Calling Flush when there is no pending data still causes the Writer
717+
// Calling Flush when there is no pending data still causes the [Writer]
718718
// to emit a sync marker of at least 4 bytes.
719719
// If the underlying writer returns an error, Flush returns that error.
720720
//
@@ -731,7 +731,7 @@ func (w *Writer) Close() error {
731731
}
732732

733733
// Reset discards the writer's state and makes it equivalent to
734-
// the result of NewWriter or NewWriterDict called with dst
734+
// the result of [NewWriter] or [NewWriterDict] called with dst
735735
// and w's level and dictionary.
736736
func (w *Writer) Reset(dst io.Writer) {
737737
if dw, ok := w.d.w.writer.(*dictWriter); ok {

src/compress/flate/inflate.go

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -65,8 +65,8 @@ func (e *WriteError) Error() string {
6565
return "flate: write error at offset " + strconv.FormatInt(e.Offset, 10) + ": " + e.Err.Error()
6666
}
6767

68-
// Resetter resets a ReadCloser returned by NewReader or NewReaderDict
69-
// to switch to a new underlying Reader. This permits reusing a ReadCloser
68+
// Resetter resets a ReadCloser returned by [NewReader] or [NewReaderDict]
69+
// to switch to a new underlying [Reader]. This permits reusing a ReadCloser
7070
// instead of allocating a new one.
7171
type Resetter interface {
7272
// Reset discards any buffered data and resets the Resetter as if it was
@@ -255,9 +255,9 @@ func (h *huffmanDecoder) init(lengths []int) bool {
255255
return true
256256
}
257257

258-
// The actual read interface needed by NewReader.
258+
// The actual read interface needed by [NewReader].
259259
// If the passed in io.Reader does not also have ReadByte,
260-
// the NewReader will introduce its own buffering.
260+
// the [NewReader] will introduce its own buffering.
261261
type Reader interface {
262262
io.Reader
263263
io.ByteReader
@@ -800,10 +800,10 @@ func (f *decompressor) Reset(r io.Reader, dict []byte) error {
800800
// to read the uncompressed version of r.
801801
// If r does not also implement [io.ByteReader],
802802
// the decompressor may read more data than necessary from r.
803-
// The reader returns io.EOF after the final block in the DEFLATE stream has
803+
// The reader returns [io.EOF] after the final block in the DEFLATE stream has
804804
// been encountered. Any trailing data after the final block is ignored.
805805
//
806-
// The ReadCloser returned by NewReader also implements Resetter.
806+
// The ReadCloser returned by NewReader also implements [Resetter].
807807
func NewReader(r io.Reader) io.ReadCloser {
808808
fixedHuffmanDecoderInit()
809809

@@ -816,13 +816,13 @@ func NewReader(r io.Reader) io.ReadCloser {
816816
return &f
817817
}
818818

819-
// NewReaderDict is like NewReader but initializes the reader
820-
// with a preset dictionary. The returned Reader behaves as if
819+
// NewReaderDict is like [NewReader] but initializes the reader
820+
// with a preset dictionary. The returned [Reader] behaves as if
821821
// the uncompressed data stream started with the given dictionary,
822822
// which has already been read. NewReaderDict is typically used
823823
// to read data compressed by NewWriterDict.
824824
//
825-
// The ReadCloser returned by NewReader also implements Resetter.
825+
// The ReadCloser returned by NewReaderDict also implements [Resetter].
826826
func NewReaderDict(r io.Reader, dict []byte) io.ReadCloser {
827827
fixedHuffmanDecoderInit()
828828

src/compress/gzip/gunzip.go

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ func noEOF(err error) error {
4545
}
4646

4747
// The gzip file stores a header giving metadata about the compressed file.
48-
// That header is exposed as the fields of the Writer and Reader structs.
48+
// That header is exposed as the fields of the [Writer] and [Reader] structs.
4949
//
5050
// Strings must be UTF-8 encoded and may only contain Unicode code points
5151
// U+0001 through U+00FF, due to limitations of the GZIP file format.
@@ -57,7 +57,7 @@ type Header struct {
5757
OS byte // operating system type
5858
}
5959

60-
// A Reader is an io.Reader that can be read to retrieve
60+
// A Reader is an [io.Reader] that can be read to retrieve
6161
// uncompressed data from a gzip-format compressed file.
6262
//
6363
// In general, a gzip file can be a concatenation of gzip files,
@@ -66,10 +66,10 @@ type Header struct {
6666
// Only the first header is recorded in the Reader fields.
6767
//
6868
// Gzip files store a length and checksum of the uncompressed data.
69-
// The Reader will return an ErrChecksum when Read
69+
// The Reader will return an [ErrChecksum] when [Reader.Read]
7070
// reaches the end of the uncompressed data if it does not
7171
// have the expected length or checksum. Clients should treat data
72-
// returned by Read as tentative until they receive the io.EOF
72+
// returned by [Reader.Read] as tentative until they receive the [io.EOF]
7373
// marking the end of the data.
7474
type Reader struct {
7575
Header // valid after NewReader or Reader.Reset
@@ -82,13 +82,13 @@ type Reader struct {
8282
multistream bool
8383
}
8484

85-
// NewReader creates a new Reader reading the given reader.
85+
// NewReader creates a new [Reader] reading the given reader.
8686
// If r does not also implement [io.ByteReader],
8787
// the decompressor may read more data than necessary from r.
8888
//
89-
// It is the caller's responsibility to call Close on the Reader when done.
89+
// It is the caller's responsibility to call Close on the [Reader] when done.
9090
//
91-
// The Reader.Header fields will be valid in the Reader returned.
91+
// The Reader.Header fields will be valid in the [Reader] returned.
9292
func NewReader(r io.Reader) (*Reader, error) {
9393
z := new(Reader)
9494
if err := z.Reset(r); err != nil {
@@ -97,9 +97,9 @@ func NewReader(r io.Reader) (*Reader, error) {
9797
return z, nil
9898
}
9999

100-
// Reset discards the Reader z's state and makes it equivalent to the
101-
// result of its original state from NewReader, but reading from r instead.
102-
// This permits reusing a Reader rather than allocating a new one.
100+
// Reset discards the [Reader] z's state and makes it equivalent to the
101+
// result of its original state from [NewReader], but reading from r instead.
102+
// This permits reusing a [Reader] rather than allocating a new one.
103103
func (z *Reader) Reset(r io.Reader) error {
104104
*z = Reader{
105105
decompressor: z.decompressor,
@@ -116,7 +116,7 @@ func (z *Reader) Reset(r io.Reader) error {
116116

117117
// Multistream controls whether the reader supports multistream files.
118118
//
119-
// If enabled (the default), the Reader expects the input to be a sequence
119+
// If enabled (the default), the [Reader] expects the input to be a sequence
120120
// of individually gzipped data streams, each with its own header and
121121
// trailer, ending at EOF. The effect is that the concatenation of a sequence
122122
// of gzipped files is treated as equivalent to the gzip of the concatenation
@@ -125,11 +125,11 @@ func (z *Reader) Reset(r io.Reader) error {
125125
// Calling Multistream(false) disables this behavior; disabling the behavior
126126
// can be useful when reading file formats that distinguish individual gzip
127127
// data streams or mix gzip data streams with other data streams.
128-
// In this mode, when the Reader reaches the end of the data stream,
129-
// Read returns io.EOF. The underlying reader must implement io.ByteReader
128+
// In this mode, when the [Reader] reaches the end of the data stream,
129+
// [Reader.Read] returns [io.EOF]. The underlying reader must implement [io.ByteReader]
130130
// in order to be left positioned just after the gzip stream.
131131
// To start the next stream, call z.Reset(r) followed by z.Multistream(false).
132-
// If there is no next stream, z.Reset(r) will return io.EOF.
132+
// If there is no next stream, z.Reset(r) will return [io.EOF].
133133
func (z *Reader) Multistream(ok bool) {
134134
z.multistream = ok
135135
}
@@ -242,7 +242,7 @@ func (z *Reader) readHeader() (hdr Header, err error) {
242242
return hdr, nil
243243
}
244244

245-
// Read implements io.Reader, reading uncompressed bytes from its underlying Reader.
245+
// Read implements [io.Reader], reading uncompressed bytes from its underlying [Reader].
246246
func (z *Reader) Read(p []byte) (n int, err error) {
247247
if z.err != nil {
248248
return 0, z.err
@@ -284,7 +284,7 @@ func (z *Reader) Read(p []byte) (n int, err error) {
284284
return n, nil
285285
}
286286

287-
// Close closes the Reader. It does not close the underlying io.Reader.
287+
// Close closes the [Reader]. It does not close the underlying [io.Reader].
288288
// In order for the GZIP checksum to be verified, the reader must be
289-
// fully consumed until the io.EOF.
289+
// fully consumed until the [io.EOF].
290290
func (z *Reader) Close() error { return z.decompressor.Close() }

src/compress/gzip/gzip.go

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -38,10 +38,10 @@ type Writer struct {
3838
err error
3939
}
4040

41-
// NewWriter returns a new Writer.
41+
// NewWriter returns a new [Writer].
4242
// Writes to the returned writer are compressed and written to w.
4343
//
44-
// It is the caller's responsibility to call Close on the Writer when done.
44+
// It is the caller's responsibility to call Close on the [Writer] when done.
4545
// Writes may be buffered and not flushed until Close.
4646
//
4747
// Callers that wish to set the fields in Writer.Header must do so before
@@ -51,11 +51,11 @@ func NewWriter(w io.Writer) *Writer {
5151
return z
5252
}
5353

54-
// NewWriterLevel is like NewWriter but specifies the compression level instead
55-
// of assuming DefaultCompression.
54+
// NewWriterLevel is like [NewWriter] but specifies the compression level instead
55+
// of assuming [DefaultCompression].
5656
//
57-
// The compression level can be DefaultCompression, NoCompression, HuffmanOnly
58-
// or any integer value between BestSpeed and BestCompression inclusive.
57+
// The compression level can be [DefaultCompression], [NoCompression], [HuffmanOnly]
58+
// or any integer value between [BestSpeed] and [BestCompression] inclusive.
5959
// The error returned will be nil if the level is valid.
6060
func NewWriterLevel(w io.Writer, level int) (*Writer, error) {
6161
if level < HuffmanOnly || level > BestCompression {
@@ -81,9 +81,9 @@ func (z *Writer) init(w io.Writer, level int) {
8181
}
8282
}
8383

84-
// Reset discards the Writer z's state and makes it equivalent to the
85-
// result of its original state from NewWriter or NewWriterLevel, but
86-
// writing to w instead. This permits reusing a Writer rather than
84+
// Reset discards the [Writer] z's state and makes it equivalent to the
85+
// result of its original state from [NewWriter] or [NewWriterLevel], but
86+
// writing to w instead. This permits reusing a [Writer] rather than
8787
// allocating a new one.
8888
func (z *Writer) Reset(w io.Writer) {
8989
z.init(w, z.level)
@@ -134,8 +134,8 @@ func (z *Writer) writeString(s string) (err error) {
134134
return err
135135
}
136136

137-
// Write writes a compressed form of p to the underlying io.Writer. The
138-
// compressed bytes are not necessarily flushed until the Writer is closed.
137+
// Write writes a compressed form of p to the underlying [io.Writer]. The
138+
// compressed bytes are not necessarily flushed until the [Writer] is closed.
139139
func (z *Writer) Write(p []byte) (int, error) {
140140
if z.err != nil {
141141
return 0, z.err
@@ -222,9 +222,9 @@ func (z *Writer) Flush() error {
222222
return z.err
223223
}
224224

225-
// Close closes the Writer by flushing any unwritten data to the underlying
226-
// io.Writer and writing the GZIP footer.
227-
// It does not close the underlying io.Writer.
225+
// Close closes the [Writer] by flushing any unwritten data to the underlying
226+
// [io.Writer] and writing the GZIP footer.
227+
// It does not close the underlying [io.Writer].
228228
func (z *Writer) Close() error {
229229
if z.err != nil {
230230
return z.err

src/compress/lzw/reader.go

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,7 @@ func (r *Reader) readMSB() (uint16, error) {
118118
return code, nil
119119
}
120120

121-
// Read implements io.Reader, reading uncompressed bytes from its underlying Reader.
121+
// Read implements io.Reader, reading uncompressed bytes from its underlying [Reader].
122122
func (r *Reader) Read(b []byte) (int, error) {
123123
for {
124124
if len(r.toRead) > 0 {
@@ -225,22 +225,22 @@ loop:
225225

226226
var errClosed = errors.New("lzw: reader/writer is closed")
227227

228-
// Close closes the Reader and returns an error for any future read operation.
229-
// It does not close the underlying io.Reader.
228+
// Close closes the [Reader] and returns an error for any future read operation.
229+
// It does not close the underlying [io.Reader].
230230
func (r *Reader) Close() error {
231231
r.err = errClosed // in case any Reads come along
232232
return nil
233233
}
234234

235-
// Reset clears the Reader's state and allows it to be reused again
236-
// as a new Reader.
235+
// Reset clears the [Reader]'s state and allows it to be reused again
236+
// as a new [Reader].
237237
func (r *Reader) Reset(src io.Reader, order Order, litWidth int) {
238238
*r = Reader{}
239239
r.init(src, order, litWidth)
240240
}
241241

242-
// NewReader creates a new io.ReadCloser.
243-
// Reads from the returned io.ReadCloser read and decompress data from r.
242+
// NewReader creates a new [io.ReadCloser].
243+
// Reads from the returned [io.ReadCloser] read and decompress data from r.
244244
// If r does not also implement [io.ByteReader],
245245
// the decompressor may read more data than necessary from r.
246246
// It is the caller's responsibility to call Close on the ReadCloser when
@@ -249,8 +249,8 @@ func (r *Reader) Reset(src io.Reader, order Order, litWidth int) {
249249
// range [2,8] and is typically 8. It must equal the litWidth
250250
// used during compression.
251251
//
252-
// It is guaranteed that the underlying type of the returned io.ReadCloser
253-
// is a *Reader.
252+
// It is guaranteed that the underlying type of the returned [io.ReadCloser]
253+
// is a *[Reader].
254254
func NewReader(r io.Reader, order Order, litWidth int) io.ReadCloser {
255255
return newReader(r, order, litWidth)
256256
}

src/compress/lzw/writer.go

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ const (
3232
)
3333

3434
// Writer is an LZW compressor. It writes the compressed form of the data
35-
// to an underlying writer (see NewWriter).
35+
// to an underlying writer (see [NewWriter]).
3636
type Writer struct {
3737
// w is the writer that compressed bytes are written to.
3838
w writer
@@ -195,7 +195,7 @@ loop:
195195
return n, nil
196196
}
197197

198-
// Close closes the Writer, flushing any pending output. It does not close
198+
// Close closes the [Writer], flushing any pending output. It does not close
199199
// w's underlying writer.
200200
func (w *Writer) Close() error {
201201
if w.err != nil {
@@ -238,22 +238,22 @@ func (w *Writer) Close() error {
238238
return w.w.Flush()
239239
}
240240

241-
// Reset clears the Writer's state and allows it to be reused again
242-
// as a new Writer.
241+
// Reset clears the[ Writer]'s state and allows it to be reused again
242+
// as a new [Writer].
243243
func (w *Writer) Reset(dst io.Writer, order Order, litWidth int) {
244244
*w = Writer{}
245245
w.init(dst, order, litWidth)
246246
}
247247

248-
// NewWriter creates a new io.WriteCloser.
249-
// Writes to the returned io.WriteCloser are compressed and written to w.
248+
// NewWriter creates a new [io.WriteCloser].
249+
// Writes to the returned [io.WriteCloser] are compressed and written to w.
250250
// It is the caller's responsibility to call Close on the WriteCloser when
251251
// finished writing.
252252
// The number of bits to use for literal codes, litWidth, must be in the
253253
// range [2,8] and is typically 8. Input bytes must be less than 1<<litWidth.
254254
//
255-
// It is guaranteed that the underlying type of the returned io.WriteCloser
256-
// is a *Writer.
255+
// It is guaranteed that the underlying type of the returned [io.WriteCloser]
256+
// is a *[Writer].
257257
func NewWriter(w io.Writer, order Order, litWidth int) io.WriteCloser {
258258
return newWriter(w, order, litWidth)
259259
}

0 commit comments

Comments
 (0)