From 6c5eb748d072451a88c704823c50316573a725b4 Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Sun, 17 May 2026 12:17:09 +0200 Subject: [PATCH] doc: godoc linting Signed-off-by: Frederic BIDON --- .github/wordlist.txt | 27 +++++++++++++++++++++++++++ bytestream.go | 14 +++++++------- client/internal/request/request.go | 4 ++-- client/runtime.go | 19 +++++++------------ csv.go | 16 ++++++++-------- form.go | 20 ++++++++++---------- interfaces.go | 2 +- middleware/denco/server.go | 2 +- middleware/seam.go | 3 ++- security/authenticator.go | 2 +- 10 files changed, 66 insertions(+), 43 deletions(-) diff --git a/.github/wordlist.txt b/.github/wordlist.txt index 9c774b88..46ae48b2 100644 --- a/.github/wordlist.txt +++ b/.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 diff --git a/bytestream.go b/bytestream.go index a1f24657..9371ea4e 100644 --- a/bytestream.go +++ b/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 { diff --git a/client/internal/request/request.go b/client/internal/request/request.go index eaaaaffb..a736c578 100644 --- a/client/internal/request/request.go +++ b/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: diff --git a/client/runtime.go b/client/runtime.go index 62576463..efbe8e49 100644 --- a/client/runtime.go +++ b/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 diff --git a/csv.go b/csv.go index 33f3af1a..11d60872 100644 --- a/csv.go +++ b/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 { diff --git a/form.go b/form.go index 7e6c971a..2293920b 100644 --- a/form.go +++ b/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 diff --git a/interfaces.go b/interfaces.go index 2d0f2d2b..85211989 100644 --- a/interfaces.go +++ b/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. diff --git a/middleware/denco/server.go b/middleware/denco/server.go index 5c36b07d..3bbbc679 100644 --- a/middleware/denco/server.go +++ b/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 { diff --git a/middleware/seam.go b/middleware/seam.go index 390d3935..b234395f 100644 --- a/middleware/seam.go +++ b/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 { diff --git a/security/authenticator.go b/security/authenticator.go index d84eb370..e521d95e 100644 --- a/security/authenticator.go +++ b/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) }