java-docs

Start with a summary sentence in third-person verb form ending with a period, then add @param for each parameter, @return for non-void methods, and @throws for each documented exception. Keep tags in declaration order and describe the contract, not the implementation.

Place the Javadoc on the record type itself and document each component with a @param tag. Do not add accessor methods just to attach Javadoc to them, since record components are documented at the type level.

Public and protected members require Javadoc because they form the API contract. Package-private members need documentation only when intent is unclear, and private members only for genuinely complex logic.

Order block tags as @param in declaration order, followed by @return, then @throws. A missing or out-of-order @param is the most common defect found in Javadoc reviews.

Use {@code} for identifiers, keywords, and literals like null or Optional.empty() in body text. Use {@link Type#member} to create cross-reference links to related types or members, and {@linkplain} for plain-text link rendering.

Warnings typically come from missing @param or @return tags, malformed inline tags, or unescaped generics in examples. Wrap multi-line examples in <pre>{@code ...}</pre> so angle brackets render literally, then rebuild.