doc: godoc linting

.github/wordlist.txt

@@ -6,18 +6,26 @@ ClientAuthInfoWriters
 CodeFactor
 CodeQL
 CompositeValidationError
+ConstantTimeCompare
+CreateHttpRequestContext
 DCO
 Denco
 Denco's
 GoDoc
+IETF
+IdleTimeout
 JSON
+KiB
 Maintainer's
+MultipartForm
 PR's
 PRs
 Petstore
+PostForm
 RESTCONF
 RapiDoc
 ReadCloser
+ReadTimeout
 Repo
 SPDX
 SpanOptions
@@ -38,38 +46,48 @@ api
 authorizer
 basePath
 basepath
+behaviour
 booleans
 bytesize
 bytestream
+canonicalized
 charset
 ci
 codebase
+codec
 codecov
 config
+contentType
+crypto
 databinding
 defaultOffer
 dependabot
 dev
 developercertificate
 env
+filesystem
 fka
 github
 godoc
 golang
 golangci
+gzip
 hasKey
 hasValue
 html
 http
 https
 implementor
+interoperating
 jsonpointer
 keepalive
 lifecycle
 linter's
 linters
 maintainer's
+maxLen
 md
+mediaType
 metalinter
 middleware
 middlewares
@@ -82,19 +100,28 @@ opentelemetry
 opentracing
 param
 params
+parentCtx
+parser's
 petstore
 pflag
 pluggability
 pre
 prepended
+recognised
 repos
 routable
 semver
 sexualized
+stdlib
+stdlib's
 structs
 symlinked
 uiOptions
 unescaped
+untrusted
 untyped
+urlencoded
 validator
 vuln
+www
+xml

bytestream.go

@@ -126,13 +126,13 @@ func ByteStreamConsumer(opts ...byteStreamOpt) Consumer {
 //
 // Supported input underlying types and interfaces, prioritized in this order:
 //
-// - [io.WriterTo] (for maximum control)
-// - [io.Reader] (performs [io.Copy]). A ReadCloser is closed before exiting.
-// - [encoding.BinaryMarshaler]
-// - error (writes as a string)
-// - []byte
-// - string
-// - struct, other slices: writes as JSON.
+//   - [io.WriterTo] (for maximum control)
+//   - [io.Reader] (performs [io.Copy]). A ReadCloser is closed before exiting.
+//   - [encoding.BinaryMarshaler]
+//   - error (writes as a string)
+//   - []byte
+//   - string
+//   - struct, other slices: writes as JSON.
 func ByteStreamProducer(opts ...byteStreamOpt) Producer {
 	var vals byteStreamOpts
 	for _, opt := range opts {

client/internal/request/request.go

@@ -50,7 +50,7 @@ var _ runtime.ClientRequest = new(Request) // ensure compliance to the interface
 //
 // The result is a [http.Request], with the following properties:
 //
-//   - file, multipart form or io.Reader body: a streaming request with an attached go routine that consumes the [io.Reader].
+//   - file, multipart form or [io.Reader] body: a streaming request with an attached go routine that consumes the [io.Reader].
 //   - buffered body: a simple request
 //
 // The caller passes the parent [context.Context] to [Request.BuildHTTPContext] and receives back a cancel
@@ -300,7 +300,7 @@ func (r *Request) SetConsumes(consumers []string) {
 // It starts by writing the request, then proceed with adding authentication,
 // then finally assembling URL or header parameters.
 //
-// The split mirrors the auth question: streaming bodies require a lazy body-copy closure during AuthenticateRequest,
+// The split mirrors the auth question: streaming bodies require a lazy body-copy closure during [AuthenticateRequest],
 // whereas buffered bodies do not.
 //
 // The returned [http.Request] carries a context derived from parentCtx that:

client/runtime.go

@@ -174,20 +174,15 @@ func (r *Runtime) CreateHTTPRequestContext(ctx context.Context, operation *runti
 	return
 }
 
-// CreateHttpRequestContext is like [Runtime.CreateHTTPRequestContext], but picks its context from the
-// [ClientOperation.Context] or from the [Runtime.Context] is they are defined.
+// CreateHttpRequest builds the [http.Request] for the given operation, using
+// [context.Background] as the request context.
 //
-// # Change in behavior with v0.30.0.
+// Any per-operation timeout declared by the operation's [runtime.ClientRequestWriter]
+// is silently ignored here, which can leak a context-cancellation channel if the
+// caller relies on it.
 //
-// Callers who define a non-zero timeout set by the [ClientOperation.Params] ([runtime.ClientRequestWriter]),
-// MUST move to [CreateHTTPRequestContext] in order to retrieve the proper cancellation function,
-// and thus avoid a systematic leak of the context cancellation channel.
-//
-// In previous versions, the value of this timeout was simply ignored here (was only honored by [Runtime.Submit].
-//
-// Callers not using timeouts this way are not affected.
-//
-// Deprecated: use [CreateHTTPRequestContext] instead, with appropriate control of the request cancellation.
+// Deprecated: use [Runtime.CreateHTTPRequestContext] instead, with explicit
+// control over the request context and its cancellation.
 func (r *Runtime) CreateHttpRequest(operation *runtime.ClientOperation) (req *http.Request, err error) { //nolint:revive
 	req, _, err = r.createHTTPRequestContext(context.Background(), operation)
 	return

csv.go

@@ -159,14 +159,14 @@ func CSVConsumer(opts ...CSVOpt) Consumer {
 //
 // Supported input underlying types and interfaces, prioritized in this order:
 //
-// - *[csv.Reader]
-// - [CSVReader] (reader options are ignored)
-// - [io.Reader]
-// - [io.WriterTo]
-// - [encoding.BinaryMarshaler]
-// - [][]string
-// - []byte
-// - string
+//   - *[csv.Reader]
+//   - [CSVReader] (reader options are ignored)
+//   - [io.Reader]
+//   - [io.WriterTo]
+//   - [encoding.BinaryMarshaler]
+//   - [][]string
+//   - []byte
+//   - string
 //
 // The producer prioritizes situations where buffering the input is not required.
 func CSVProducer(opts ...CSVOpt) Producer {

form.go

@@ -13,7 +13,7 @@ import (
 )
 
 // DefaultMaxUploadFilenameLength is the default cap applied to
-// FileHeader.Filename for each declared file when BindForm is invoked
+// FileHeader.Filename for each declared file when [BindForm] is invoked
 // without an explicit [BindFormMaxFilenameLen] option.
 //
 // Multipart headers are allocated per part; an attacker submitting
@@ -35,11 +35,11 @@ const filenamePreviewLen = 32
 // ValidateFilenameLength enforces the FileHeader.Filename length cap
 // that [BindForm] applies via [BindFormFile] declarations. Untyped
 // binder paths that fetch the file via [http.Request.FormFile]
-// directly (rather than declaring the file through BindFormFile) call
+// directly (rather than declaring the file through [BindFormFile]) call
 // this to opt into the same protection.
 //
 // Returns nil if filename length is within maxLen or maxLen <= 0.
-// Otherwise returns an *errors.ParseError suitable for direct return
+// Otherwise returns a [*errors.ParseError] suitable for direct return
 // from a parameter binder. The error embeds a truncated preview of
 // the offending filename to keep the error message bounded.
 func ValidateFilenameLength(paramName, paramIn, filename string, maxLen int) error {
@@ -59,10 +59,10 @@ func ValidateFilenameLength(paramName, paramIn, filename string, maxLen int) err
 //
 //	o.FieldName = &runtime.File{Data: file, Header: header}
 //
-// Returning a non-nil error surfaces the error in BindForm's per-field
+// Returning a non-nil error surfaces the error in [BindForm]'s per-field
 // accumulator. Errors from the binder flow through verbatim — the
 // binder is expected to produce HTTP-aware errors (e.g.
-// errors.ExceedsMaximum from go-openapi/validate).
+// [errors.ExceedsMaximum] from go-openapi/validate).
 type FileBinder func(file multipart.File, header *multipart.FileHeader) error
 
 // BindOption configures [BindForm]. The variadic style keeps simple
@@ -91,7 +91,7 @@ type formFileSpec struct {
 // This option does NOT cap total body bytes — see [BindFormMaxBody]
 // for that. The default body cap ([DefaultMaxUploadBodySize] = 32 MB)
 // is applied even when this option is not supplied, so out of the box
-// BindForm is bounded; callers with stricter or looser requirements
+// [BindForm] is bounded; callers with stricter or looser requirements
 // adjust via [BindFormMaxBody].
 func BindFormMaxParseMemory(n int64) BindOption {
 	return func(c *bindConfig) { c.maxParseMemory = n }
@@ -125,7 +125,7 @@ func BindFormMaxFilenameLen(n int) BindOption {
 
 // BindFormFile declares a file field to bind under the given form
 // name. If required is true and the field is absent, [BindForm]
-// produces the per-field error
+// produces the per-field error.
 //
 //	errors.NewParseError(name, "formData", "", http.ErrMissingFile)
 //
@@ -154,7 +154,7 @@ func BindFormFile(name string, required bool, bind FileBinder) BindOption {
 // the call returns.
 //
 // All errors produced by BindForm itself (parse failure, missing
-// required field, cap exceeded) are *errors.ParseError values built
+// required field, cap exceeded) are [*errors.ParseError] values built
 // via [errors.NewParseError], matching the untyped
 // middleware/parameter.go path. Errors returned by per-file binders
 // flow through verbatim — binders own their HTTP-aware error shape.
@@ -189,8 +189,8 @@ func BindFormFile(name string, required bool, bind FileBinder) BindOption {
 //
 // Caller responsibilities the helper does NOT cover:
 //
-//   - Set http.Server.ReadTimeout / IdleTimeout to defend against
-//     slow-read attacks.
+//   - Set [http.Server.ReadTimeout] / [http.Server.IdleTimeout] to defend
+//     against slow-read attacks.
 //   - Decompress Content-Encoding: gzip request bodies upstream if
 //     the API accepts them, using a size-limited reader.
 //   - Treat FileHeader.Filename as untrusted user input; never use

interfaces.go

@@ -103,7 +103,7 @@ type ContextValidatable interface {
 // ContentTyper is implemented by values that declare their own MIME
 // content type. The client runtime consults it in two places:
 //
-//   - on a body payload set via SetBodyParam: when the payload is a
+//   - on a body payload set via [SetBodyParam]: when the payload is a
 //     stream (io.Reader, io.ReadCloser) and ContentType returns a
 //     non-empty value, that value becomes the wire Content-Type
 //     header instead of the operation's picked consumes entry.

middleware/denco/server.go

@@ -75,7 +75,7 @@ type Handler struct {
 	Func HandlerFunc
 }
 
-// HandlerFunc is an aliase to the handler function, similar to [http.HandlerFunc].
+// HandlerFunc is an alias to the handler function, similar to [http.HandlerFunc].
 type HandlerFunc func(w http.ResponseWriter, r *http.Request, params Params)
 
 type serveMux struct {

middleware/seam.go

@@ -135,7 +135,8 @@ func Spec(basePath string, spec []byte, next http.Handler, opts ...SpecOption) h
 
 }
 
-// WithSpecPath sets the path to be joined to the base path of the [ServeSpec] [middleware].
+// WithSpecPath sets the path to be joined to the base path of the
+// spec-serving middleware (see [docui.ServeSpec]).
 //
 // This is empty by default.
 func WithSpecPath(pth string) SpecOption {

security/authenticator.go

@@ -34,7 +34,7 @@ func HTTPAuthenticator(handler func(*http.Request) (bool, any, error)) runtime.A
 
 // HttpAuthenticator aliases [HTTPAuthenticator] for backward-compatibility.
 //
-// Deprecated: use HTTPAuthenticator instead.
+// Deprecated: use [HTTPAuthenticator] instead.
 func HttpAuthenticator(handler func(*http.Request) (bool, any, error)) runtime.Authenticator { //nolint:revive
 	return HTTPAuthenticator(handler)
 }