writing-javadoc

---
name: writing-javadoc
description: Use when writing or editing Javadoc for Lettuce public API — new methods, classes, deprecations, or when a reviewer asks to fix or improve doc comments. Points to the full house ruleset in .agents/docs/javadoc.md (imperative method summaries, fixed tag order, @param/@return/@throws/@since/@deprecated house forms) and the rule that command-interface Javadoc is written on the sync interface first and mirrored to the other flavors. Trigger on "write javadoc for", "document this method", "add a deprecation notice", "fix the doc comment".
---

# Writing Javadoc for Lettuce

The complete, authoritative ruleset is **[.agents/docs/javadoc.md](../../../.agents/docs/javadoc.md)** —
read it before writing. This skill is the operating checklist; the doc wins on any
detail.

## Before you write

- **Is it a command interface?** The command interfaces are hand-edited, with the
  **sync** interface's Javadoc as the reference text. Write or fix the comment on
  the sync method first, then mirror it to **every** flavor that declares the
  method, with the flavor-appropriate `@return` phrasing (`RedisFuture`,
  `Mono`/`Flux`, …):
  - `src/main/java/io/lettuce/core/api/{sync,async,reactive}/`
  - the Kotlin coroutine interfaces (`src/main/kotlin/…/api/coroutines/`)
  - the cluster node-selection interfaces
    (`src/main/java/io/lettuce/core/cluster/api/{sync,async}/NodeSelection…`)
  - the Sentinel interfaces (`src/main/java/io/lettuce/core/sentinel/api/…` and
    their Kotlin flavor)

  Javadoc parity is **not** test-enforced — keep the flavors in sync by hand. See
  [api-consistency.md](../../../.agents/docs/api-consistency.md).

## The rules most often gotten wrong

1. **Golden rule:** document the caller-facing contract (inputs, outputs, effects,
   errors, nullability) — never implementation details or refactor rationale.
2. **First sentence:** imperative verb for methods ("Append…", "Get…", "Remove…"),
   noun phrase for types. Not "This method…". Ends in a clean period.
3. **Tag order:** `@param` → `@return` → `@throws` → `@author` → `@since` → `@see`
   → `@deprecated`.
4. **`@param`** for every parameter (type params `<K>`/`<V>` first); state
   nullability with the house phrases `must not be {@code null}.` / `can be {@code null}.`
5. **`@return`** for non-void; describe the value and its meaningful states, not the
   type.
6. **`@since`** is a bare version — `@since 7.7` (see .agents/docs/javadoc.md for deriving
   the version from the build).
7. **`@deprecated`** — keep the `@Deprecated` annotation and the tag in sync; house
   form: `@deprecated since <version>, use {@link Replacement} instead; scheduled for
   removal in a future major release.`
8. **`@author`** on types only — the *maintainer's* name (an agent must not invent
   one); don't reorder existing authors.
9. Use `{@code null}` for literals; `{@link}` only to types resolvable on the
   compile classpath (else `{@code TypeName}`).

## Verify, don't guess

Match the surrounding file, and consult `.agents/docs/javadoc.md` for any subtle case
rather than inventing a rule. Javadoc lint is off in the build (`<doclint>none</doclint>`),
so review is the only check — get it right by hand.

More agent context in redis/lettuce

4 other files this repository gives its agents.