[docs] Update documentation for features from 2026-05-23

[github-actions]

Documentation Updates - 2026-05-23

This PR updates the documentation based on features merged in the last 24 hours.

Features Documented

• Validate() startup checks for APIKeyHandler, EmailVerificationHandler, and PasswordResetHandler (from Add fail-fast Validate() checks to EmailVerification, PasswordReset, and APIKey handlers #340)

📝 Detailed Changes & References

Changes Made

• Updated docs/handler/api-keys.md — added h.Validate() call to Configuration example and note explaining that APIKeys and URLParamFunc are required; nil URLParamFunc would cause a runtime panic on Delete
• Updated docs/handler/email-verification.md — added h.Validate() call to Configuration example and note explaining that Users and Verifications are required
• Updated docs/handler/password-reset.md — added h.Validate() call to Configuration example and note explaining that Users and Resets are required

Merged PRs Referenced

• Add fail-fast Validate() checks to EmailVerification, PasswordReset, and APIKey handlers #340 — Add fail-fast Validate() checks to EmailVerification, PasswordReset, and APIKey handlers

Skipped Issues

No open documentation issues found.

Notes

The Validate() pattern already existed in magic-links.md and totp.md; these changes bring the remaining three handlers to parity.

Generated by Daily Documentation Updater · ● 1.1M · ◷

Add this agentic workflows to your repo

To install this agentic workflow, run

gh aw add github/gh-aw/.github/workflows/daily-doc-updater.md@a70dd401e64b94aad51cc3aeb6c8e639873c1457

• expires on May 24, 2026, 8:49 PM UTC

Greptile Summary

This PR consolidates the Validate() startup-check documentation across APIKeyHandler, EmailVerificationHandler, and PasswordResetHandler, bringing them to parity with the existing pattern in magic-links.md and totp.md. The previously flagged duplicate code blocks and contradictory field lists in email-verification.md and password-reset.md are resolved.

• api-keys.md: Merges the separate Validate() code block into the main configuration snippet; the prose description no longer lists APIKeys as a required field (only URLParamFunc appears in the example error), which is inconsistent with how the other two handlers document their validated fields.
• email-verification.md: Removes duplicate h.Validate() block and unifies the field list to correctly name all three required fields (Users, Verifications, SendEmail).
• password-reset.md: Same consolidation — single h.Validate() block, corrected field list (Users, Resets, SendResetEmail), pre-existing Behaviour-section warning retained.

Confidence Score: 5/5

Documentation-only changes; no runtime code is modified. Safe to merge.

All three files are pure Markdown documentation. The email-verification.md and password-reset.md changes are clean and correct. The api-keys.md change drops an explicit mention of APIKeys as a required field from the Validate() description, leaving it slightly inconsistent with the other handlers, but this does not affect runtime behavior.

docs/handler/api-keys.md — the Validate() description no longer lists APIKeys as a required field.

Important Files Changed

Filename	Overview
docs/handler/api-keys.md	Merged separate Validate() code block into the main configuration block; APIKeys is no longer listed as a required field in the Validate() description, unlike the other two handlers.
docs/handler/email-verification.md	Consolidated duplicate Validate() blocks and contradictory field lists into a single, correct description; all three required fields (Users, Verifications, SendEmail) are now listed.
docs/handler/password-reset.md	Resolved previously flagged duplicate Validate() block and contradictory field list; single note now correctly lists Users, Resets, and SendResetEmail.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Server Startup] --> B["h.Validate()"]
    B --> C{All required\nfields set?}
    C -- No --> D["log.Fatal(err)\nDescriptive error message"]
    C -- Yes --> E[Mount handler routes]

    subgraph APIKeyHandler
        F["APIKeys (required)"]
        G["URLParamFunc (required)"]
        H["Prefix (optional)"]
    end

    subgraph EmailVerificationHandler
        I["Users (required)"]
        J["Verifications (required)"]
        K["SendEmail (required)"]
        L["TokenTTL (optional)"]
    end

    subgraph PasswordResetHandler
        M["Users (required)"]
        N["Resets (required)"]
        O["SendResetEmail (required)"]
        P["TokenTTL / RateLimiter (optional)"]
    end

    APIKeyHandler --> B
    EmailVerificationHandler --> B
    PasswordResetHandler --> B

Loading

Comments Outside Diff (2)

1. docs/handler/email-verification.md, line 20-32 (link)

   Duplicate Validate() block and contradictory field list

   The new content (lines 15–20) and the pre-existing content (lines 24–32) now both tell readers to call h.Validate(), showing two separate identical code examples in the same section. Worse, the two descriptions disagree on what the function actually checks: line 20 says only Users and Verifications are required, while line 24 says all three fields (Users, Verifications, SendEmail) are checked. A reader relying on the new note will think SendEmail is not validated and may omit it in a non-test setup. The old standalone paragraph and its code block should be removed, and the single remaining note should reflect the actual set of fields checked by Validate().

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: docs/handler/email-verification.md
   Line: 20-32
   
   Comment:
   **Duplicate `Validate()` block and contradictory field list**
   
   The new content (lines 15–20) and the pre-existing content (lines 24–32) now both tell readers to call `h.Validate()`, showing two separate identical code examples in the same section. Worse, the two descriptions disagree on what the function actually checks: line 20 says only `Users` and `Verifications` are required, while line 24 says all three fields (`Users`, `Verifications`, `SendEmail`) are checked. A reader relying on the new note will think `SendEmail` is not validated and may omit it in a non-test setup. The old standalone paragraph and its code block should be removed, and the single remaining note should reflect the actual set of fields checked by `Validate()`.
   
   How can I resolve this? If you propose a fix, please make it concise.

   

2. docs/handler/password-reset.md, line 21-34 (link)

   Duplicate Validate() block and contradictory field list

   The newly added note on line 21 says Validate only checks Users and Resets, but the pre-existing paragraph on line 26 says it catches all three required fields (Users, Resets, SendResetEmail), and a second identical h.Validate() code block appears on lines 29–31. A developer reading only the new note would conclude SendResetEmail is not a required field, potentially shipping a handler that returns HTTP 503 on every reset request. The old standalone paragraph and its code block should be removed, with the inline note updated to list all fields actually validated by Validate().

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: docs/handler/password-reset.md
   Line: 21-34
   
   Comment:
   **Duplicate `Validate()` block and contradictory field list**
   
   The newly added note on line 21 says `Validate` only checks `Users` and `Resets`, but the pre-existing paragraph on line 26 says it catches all three required fields (`Users`, `Resets`, `SendResetEmail`), and a second identical `h.Validate()` code block appears on lines 29–31. A developer reading only the new note would conclude `SendResetEmail` is not a required field, potentially shipping a handler that returns HTTP 503 on every reset request. The old standalone paragraph and its code block should be removed, with the inline note updated to list all fields actually validated by `Validate()`.
   
   How can I resolve this? If you propose a fix, please make it concise.

   

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
docs/handler/api-keys.md:19
`Validate()` description is missing `APIKeys` as a required field, unlike the parallel descriptions in `email-verification.md` (listing all three fields) and `password-reset.md`. The removed paragraph previously named both `APIKeys` and `URLParamFunc` explicitly; the remaining text only surfaces `URLParamFunc` via an example error. A developer could reasonably conclude `APIKeys` is optional.

```suggestion
`Validate()` returns an error if `APIKeys` or `URLParamFunc` is `nil`, with a descriptive message such as `"APIKeyHandler misconfigured: URLParamFunc is required"` so the cause is immediately obvious in logs. Call it once at server startup so missing dependencies surface immediately rather than at the first request. `Delete` also includes a defensive nil guard for `URLParamFunc` and returns HTTP 500 if it is nil at request time, but calling `Validate()` at startup is strongly preferred.
```

_{Reviews (3): Last reviewed commit: "docs(handler): fix contradictory Validat..." | Re-trigger Greptile}