From: cui fliter Date: Fri, 3 Nov 2023 09:04:15 +0000 (+0800) Subject: mime: add available godoc link X-Git-Tag: go1.23rc1~811 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=d9f97467946556e94817acbb35fef7f536afed5f;p=gostls13.git mime: add available godoc link Change-Id: I66ec9edc71f4c1207135e4248003a7457e456931 Reviewed-on: https://go-review.googlesource.com/c/go/+/539576 Reviewed-by: Damien Neil LUCI-TryBot-Result: Go LUCI TryBot-Result: Gopher Robot Reviewed-by: David Chase Run-TryBot: shuang cui --- diff --git a/src/mime/encodedword.go b/src/mime/encodedword.go index e6b470b1fb..856433f8f3 100644 --- a/src/mime/encodedword.go +++ b/src/mime/encodedword.go @@ -226,7 +226,7 @@ func (d *WordDecoder) Decode(word string) (string, error) { } // DecodeHeader decodes all encoded-words of the given string. It returns an -// error if and only if CharsetReader of d returns an error. +// error if and only if WordDecoder.CharsetReader of d returns an error. func (d *WordDecoder) DecodeHeader(header string) (string, error) { // If there is no encoded-word, returns before creating a buffer. i := strings.Index(header, "=?") diff --git a/src/mime/mediatype.go b/src/mime/mediatype.go index bc8d417e62..40d919e7a8 100644 --- a/src/mime/mediatype.go +++ b/src/mime/mediatype.go @@ -121,7 +121,7 @@ func checkMediaTypeDisposition(s string) error { return nil } -// ErrInvalidMediaParameter is returned by ParseMediaType if +// ErrInvalidMediaParameter is returned by [ParseMediaType] if // the media type value was found but there was an error parsing // the optional parameters var ErrInvalidMediaParameter = errors.New("mime: invalid media parameter") @@ -133,7 +133,7 @@ var ErrInvalidMediaParameter = errors.New("mime: invalid media parameter") // to lowercase and trimmed of white space and a non-nil map. // If there is an error parsing the optional parameter, // the media type will be returned along with the error -// ErrInvalidMediaParameter. +// [ErrInvalidMediaParameter]. // The returned map, params, maps from the lowercase // attribute to the attribute value with its case preserved. func ParseMediaType(v string) (mediatype string, params map[string]string, err error) { diff --git a/src/mime/multipart/formdata.go b/src/mime/multipart/formdata.go index e0a63a66ae..d0e0151a6f 100644 --- a/src/mime/multipart/formdata.go +++ b/src/mime/multipart/formdata.go @@ -27,7 +27,7 @@ var ErrMessageTooLarge = errors.New("multipart: message too large") // It stores up to maxMemory bytes + 10MB (reserved for non-file parts) // in memory. File parts which can't be stored in memory will be stored on // disk in temporary files. -// It returns ErrMessageTooLarge if all non-file parts can't be stored in +// It returns [ErrMessageTooLarge] if all non-file parts can't be stored in // memory. func (r *Reader) ReadForm(maxMemory int64) (*Form, error) { return r.readForm(maxMemory) @@ -228,7 +228,7 @@ func mimeHeaderSize(h textproto.MIMEHeader) (size int64) { // Form is a parsed multipart form. // Its File parts are stored either in memory or on disk, -// and are accessible via the *FileHeader's Open method. +// and are accessible via the [*FileHeader]'s Open method. // Its Value parts are stored as strings. // Both are keyed by field name. type Form struct { @@ -236,7 +236,7 @@ type Form struct { File map[string][]*FileHeader } -// RemoveAll removes any temporary files associated with a Form. +// RemoveAll removes any temporary files associated with a [Form]. func (f *Form) RemoveAll() error { var err error for _, fhs := range f.File { @@ -264,7 +264,7 @@ type FileHeader struct { tmpshared bool } -// Open opens and returns the FileHeader's associated File. +// Open opens and returns the [FileHeader]'s associated File. func (fh *FileHeader) Open() (File, error) { if b := fh.content; b != nil { r := io.NewSectionReader(bytes.NewReader(b), 0, int64(len(b))) diff --git a/src/mime/multipart/multipart.go b/src/mime/multipart/multipart.go index 00a7e5fe46..17088bc30e 100644 --- a/src/mime/multipart/multipart.go +++ b/src/mime/multipart/multipart.go @@ -15,8 +15,8 @@ bodies generated by popular browsers. To protect against malicious inputs, this package sets limits on the size of the MIME data it processes. -Reader.NextPart and Reader.NextRawPart limit the number of headers in a -part to 10000 and Reader.ReadForm limits the total number of headers in all +[Reader.NextPart] and [Reader.NextRawPart] limit the number of headers in a +part to 10000 and [Reader.ReadForm] limits the total number of headers in all FileHeaders to 10000. These limits may be adjusted with the GODEBUG=multipartmaxheaders= setting. @@ -85,7 +85,7 @@ func (p *Part) FormName() string { return p.dispositionParams["name"] } -// FileName returns the filename parameter of the Part's Content-Disposition +// FileName returns the filename parameter of the [Part]'s Content-Disposition // header. If not empty, the filename is passed through filepath.Base (which is // platform dependent) before being returned. func (p *Part) FileName() string { @@ -110,11 +110,11 @@ func (p *Part) parseContentDisposition() { } } -// NewReader creates a new multipart Reader reading from r using the +// NewReader creates a new multipart [Reader] reading from r using the // given MIME boundary. // // The boundary is usually obtained from the "boundary" parameter of -// the message's "Content-Type" header. Use mime.ParseMediaType to +// the message's "Content-Type" header. Use [mime.ParseMediaType] to // parse such headers. func NewReader(r io.Reader, boundary string) *Reader { b := []byte("\r\n--" + boundary + "--") @@ -363,7 +363,7 @@ func maxMIMEHeaders() int64 { } // NextPart returns the next part in the multipart or an error. -// When there are no more parts, the error io.EOF is returned. +// When there are no more parts, the error [io.EOF] is returned. // // As a special case, if the "Content-Transfer-Encoding" header // has a value of "quoted-printable", that header is instead @@ -373,9 +373,9 @@ func (r *Reader) NextPart() (*Part, error) { } // NextRawPart returns the next part in the multipart or an error. -// When there are no more parts, the error io.EOF is returned. +// When there are no more parts, the error [io.EOF] is returned. // -// Unlike NextPart, it does not have special handling for +// Unlike [Reader.NextPart], it does not have special handling for // "Content-Transfer-Encoding: quoted-printable". func (r *Reader) NextRawPart() (*Part, error) { return r.nextPart(true, maxMIMEHeaderSize, maxMIMEHeaders()) diff --git a/src/mime/multipart/readmimeheader.go b/src/mime/multipart/readmimeheader.go index 25aa6e2092..c6825069b0 100644 --- a/src/mime/multipart/readmimeheader.go +++ b/src/mime/multipart/readmimeheader.go @@ -1,6 +1,7 @@ // Copyright 2023 The Go Authors. All rights reserved. // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file. + package multipart import ( @@ -8,7 +9,7 @@ import ( _ "unsafe" // for go:linkname ) -// readMIMEHeader is defined in package net/textproto. +// readMIMEHeader is defined in package [net/textproto]. // //go:linkname readMIMEHeader net/textproto.readMIMEHeader func readMIMEHeader(r *textproto.Reader, maxMemory, maxHeaders int64) (textproto.MIMEHeader, error) diff --git a/src/mime/multipart/writer.go b/src/mime/multipart/writer.go index d1ff151a7d..a265c68fe0 100644 --- a/src/mime/multipart/writer.go +++ b/src/mime/multipart/writer.go @@ -22,7 +22,7 @@ type Writer struct { lastpart *part } -// NewWriter returns a new multipart Writer with a random boundary, +// NewWriter returns a new multipart [Writer] with a random boundary, // writing to w. func NewWriter(w io.Writer) *Writer { return &Writer{ @@ -31,12 +31,12 @@ func NewWriter(w io.Writer) *Writer { } } -// Boundary returns the Writer's boundary. +// Boundary returns the [Writer]'s boundary. func (w *Writer) Boundary() string { return w.boundary } -// SetBoundary overrides the Writer's default randomly-generated +// SetBoundary overrides the [Writer]'s default randomly-generated // boundary separator with an explicit value. // // SetBoundary must be called before any parts are created, may only @@ -70,7 +70,7 @@ func (w *Writer) SetBoundary(boundary string) error { } // FormDataContentType returns the Content-Type for an HTTP -// multipart/form-data with this Writer's Boundary. +// multipart/form-data with this [Writer]'s Boundary. func (w *Writer) FormDataContentType() string { b := w.boundary // We must quote the boundary if it contains any of the @@ -92,7 +92,7 @@ func randomBoundary() string { // CreatePart creates a new multipart section with the provided // header. The body of the part should be written to the returned -// Writer. After calling CreatePart, any previous part may no longer +// [Writer]. After calling CreatePart, any previous part may no longer // be written to. func (w *Writer) CreatePart(header textproto.MIMEHeader) (io.Writer, error) { if w.lastpart != nil { @@ -135,7 +135,7 @@ func escapeQuotes(s string) string { return quoteEscaper.Replace(s) } -// CreateFormFile is a convenience wrapper around CreatePart. It creates +// CreateFormFile is a convenience wrapper around [Writer.CreatePart]. It creates // a new form-data header with the provided field name and file name. func (w *Writer) CreateFormFile(fieldname, filename string) (io.Writer, error) { h := make(textproto.MIMEHeader) @@ -146,7 +146,7 @@ func (w *Writer) CreateFormFile(fieldname, filename string) (io.Writer, error) { return w.CreatePart(h) } -// CreateFormField calls CreatePart with a header using the +// CreateFormField calls [Writer.CreatePart] with a header using the // given field name. func (w *Writer) CreateFormField(fieldname string) (io.Writer, error) { h := make(textproto.MIMEHeader) @@ -155,7 +155,7 @@ func (w *Writer) CreateFormField(fieldname string) (io.Writer, error) { return w.CreatePart(h) } -// WriteField calls CreateFormField and then writes the given value. +// WriteField calls [Writer.CreateFormField] and then writes the given value. func (w *Writer) WriteField(fieldname, value string) error { p, err := w.CreateFormField(fieldname) if err != nil { diff --git a/src/mime/quotedprintable/writer.go b/src/mime/quotedprintable/writer.go index 16ea0bf7d6..69b5a11232 100644 --- a/src/mime/quotedprintable/writer.go +++ b/src/mime/quotedprintable/writer.go @@ -8,7 +8,7 @@ import "io" const lineMaxLen = 76 -// A Writer is a quoted-printable writer that implements io.WriteCloser. +// A Writer is a quoted-printable writer that implements [io.WriteCloser]. type Writer struct { // Binary mode treats the writer's input as pure binary and processes end of // line bytes as binary data. @@ -20,14 +20,14 @@ type Writer struct { cr bool } -// NewWriter returns a new Writer that writes to w. +// NewWriter returns a new [Writer] that writes to w. func NewWriter(w io.Writer) *Writer { return &Writer{w: w} } // Write encodes p using quoted-printable encoding and writes it to the -// underlying io.Writer. It limits line length to 76 characters. The encoded -// bytes are not necessarily flushed until the Writer is closed. +// underlying [io.Writer]. It limits line length to 76 characters. The encoded +// bytes are not necessarily flushed until the [Writer] is closed. func (w *Writer) Write(p []byte) (n int, err error) { for i, b := range p { switch { @@ -62,8 +62,8 @@ func (w *Writer) Write(p []byte) (n int, err error) { return len(p), nil } -// Close closes the Writer, flushing any unwritten data to the underlying -// io.Writer, but does not close the underlying io.Writer. +// Close closes the [Writer], flushing any unwritten data to the underlying +// [io.Writer], but does not close the underlying io.Writer. func (w *Writer) Close() error { if err := w.checkLastByte(); err != nil { return err