Writing Javadoc Agent Skill

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 interfaces under

src/main/java/io/lettuce/core/api/{sync,async,reactive}/ are generated

(@generated marker). Edit the Javadoc in the template at

src/main/templates/io/lettuce/core/api/<Group>Commands.java, not the generated

file — the template comment feeds every flavor. See architecture.md.

The rules most often gotten wrong

• Golden rule: document the caller-facing contract (inputs, outputs, effects,

errors, nullability) — never implementation details or refactor rationale.

• First sentence: imperative verb for methods ("Append…", "Get…", "Remove…"),

noun phrase for types. Not "This method…". Ends in a clean period.

• Tag order: @param → @return → @throws → @author → @since → @see

→ @deprecated.

• @param for every parameter (type params <K>/<V> first); state

nullability with the house phrases must not be {@code null}. / can be {@code null}.

• @return for non-void; describe the value and its meaningful states, not the

type.

• @since is a bare version — @since 7.7 (see .agents/docs/javadoc.md for deriving

the version from the build).

• @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.`

• @author on types only — the *maintainer's* name (an agent must not invent

one); don't reorder existing authors.

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