java-docs

name	java-docs
description	Javadoc and Java API documentation guidance. Use when documenting public Java types, controllers, service contracts, records, exceptions, or non-obvious backend behavior in backend/**/*.java.

Java Documentation Best Practices

Source: adapted from github/awesome-copilot skill java-docs and this repository's preference for succinct, useful comments.

When to Use

• Adding or reviewing Javadoc for public/protected Java APIs
• Documenting records, service contracts, exceptions, or extension points
• Clarifying non-obvious behavior that tests alone will not make easy to discover

Procedure

1. Document public and protected types and members when they form a reusable contract or would be unclear to a caller.
2. Do not add Javadoc that merely repeats method names or obvious implementation details.
3. Make the first sentence a concise summary ending with a period.
4. Use @param for method parameters. Start descriptions with lowercase text and omit trailing periods unless the description is a full sentence.
5. Use @return when the return value needs explanation.
6. Use @throws for exceptions that callers should deliberately handle.
7. Use {@code ...} for inline code and <pre>{@code ...}</pre> for multi-line examples.
8. Use {@inheritDoc} when inherited documentation remains accurate; document differences when behavior changes.
9. Avoid @author and @version unless the project already uses them consistently.
10. Prefer examples that are stable and small. Keep larger guidance in Markdown docs or ADRs.

Review Checklist

• Comments clarify caller-facing behavior or non-obvious decisions
• Public contracts mention important validation, side effects, or exceptions
• Javadoc tags are complete and accurate
• No noisy comments on self-explanatory code