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 — 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.

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.