Docs: explain what distinguishes validate from other packages #3

New Issue

2026-09-07T12:22:50Z

claude commented

2026-09-07 12:22:50 +00:00

The README is three lines. A reader arriving from a search can't tell why they'd pick this over go-playground/validator/v10 or go-ozzo/ozzo-validation, and the design choices that make it worth keeping are invisible.

What the docs should get across

Four properties distinguish this package from the ones people usually reach for:

A validator is just func(T) error. No Rule interface, no struct tags. You can write one inline, store []func(string) error, range over them — no adapter.
Generics-native combinators. All, In, Equal, NotIn are type-checked at compile time. The popular libraries predate generics and use interface{} + reflection.
No reflection, no tags, no dependencies. Purely value-level; nothing imports outside the standard library.
Errors are plain sentinels. errors.Is(err, ErrInvalidEmail) composes with the standard errors package instead of a library-specific error type.

Closest paradigm relative is ozzo-validation (composable rules in code); the differentiator is "generics + bare functions + zero deps", at the cost of struct-level ergonomics (see #4) and all-errors-at-once aggregation (see #5).

Suggested plan

Rewrite the README intro: a positioning paragraph, then a short "Why not X" section contrasting with validator/v10 (tags), ozzo-validation (Rule + interface{}), govalidator (IsX funcs).
Add a doc.go package comment carrying the same summary so it renders on the package doc page.
Add runnable Example functions (some already exist) for: a hand-written inline validator composed with All; In / Equal type safety; matching a returned error with errors.Is in an HTTP handler. These double as tested documentation.
A short "Not a fit if…" note — struct-tag validation, i18n/translation, or a large catalogue of built-ins → point at validator/v10.
Once #6 lands, list the built-in validators in a table.

The README is three lines. A reader arriving from a search can't tell why they'd pick this over `go-playground/validator/v10` or `go-ozzo/ozzo-validation`, and the design choices that make it worth keeping are invisible. ## What the docs should get across Four properties distinguish this package from the ones people usually reach for: 1. **A validator is just `func(T) error`.** No `Rule` interface, no struct tags. You can write one inline, store `[]func(string) error`, range over them — no adapter. 2. **Generics-native combinators.** `All`, `In`, `Equal`, `NotIn` are type-checked at compile time. The popular libraries predate generics and use `interface{}` + reflection. 3. **No reflection, no tags, no dependencies.** Purely value-level; nothing imports outside the standard library. 4. **Errors are plain sentinels.** `errors.Is(err, ErrInvalidEmail)` composes with the standard `errors` package instead of a library-specific error type. Closest paradigm relative is ozzo-validation (composable rules in code); the differentiator is "generics + bare functions + zero deps", at the cost of struct-level ergonomics (see #4) and all-errors-at-once aggregation (see #5). ## Suggested plan - [ ] Rewrite the README intro: a positioning paragraph, then a short **"Why not X"** section contrasting with `validator/v10` (tags), `ozzo-validation` (`Rule` + `interface{}`), `govalidator` (`IsX` funcs). - [ ] Add a `doc.go` package comment carrying the same summary so it renders on the package doc page. - [ ] Add runnable `Example` functions (some already exist) for: a hand-written inline validator composed with `All`; `In` / `Equal` type safety; matching a returned error with `errors.Is` in an HTTP handler. These double as tested documentation. - [ ] A short **"Not a fit if…"** note — struct-tag validation, i18n/translation, or a large catalogue of built-ins → point at `validator/v10`. - [ ] Once #6 lands, list the built-in validators in a table.

aneurin commented

2026-09-07 12:56:05 +00:00

Before starting this task, analyse all code and check whether code comments are correct/useful and update as needed.

claude referenced this issue from a commit

2026-09-07 13:01:07 +00:00

fix incorrect and vague doc comments

claude referenced this issue from a commit

2026-09-07 13:01:07 +00:00

docs: positioning README, package doc, usage examples

claude referenced a pull request that will close this issue

2026-09-07 13:01:19 +00:00

docs: explain what distinguishes validate (+ comment audit) #11