Java documentation
Add or improve Javadoc so Java APIs communicate behavior, parameters, return values, exceptions, inheritance, generics, deprecations, and examples without restating obvious implementation details.
When to invoke
- "Add Javadoc to these Java classes."
- "Review this Java documentation for best practices."
- "Document public and protected methods with Javadoc."
- "Fix missing
@param, @return, or @throws tags."
Documentation coverage
| Element |
Requirement |
Notes |
| Public types and members |
Document with Javadoc comments. |
Treat this as mandatory API documentation. |
| Protected members |
Document with Javadoc comments. |
Subclasses depend on the contract. |
| Package-private and private members |
Document when complex or not self-explanatory. |
Prefer clear code over comments for obvious internals. |
| Generic type parameters |
Use @param <T>. |
Describe what the type represents, not its Java syntax. |
| Exceptions |
Use @throws or @exception. |
Document conditions that callers can act on. |
| Deprecations |
Use @deprecated and provide an alternative. |
Pair with the Java @Deprecated annotation when changing code. |
Javadoc tag rules
| Tag or construct |
Use |
Style rule |
| Summary sentence |
First sentence of every Javadoc comment. |
Concise overview ending with a period. |
@param |
Method parameters. |
Description starts with a lowercase letter and does not end with a period. |
@return |
Non-void return values. |
Explain meaning, units, nullability, and special cases. |
@throws / @exception |
Exceptions thrown by methods. |
Prefer @throws; include the triggering condition. |
@see |
References to other types or members. |
Use for related APIs, not generic external reading. |
{@inheritDoc} |
Inherit base-class or interface documentation. |
Use unless behavior materially changes; document differences when it does. |
{@code} |
Inline code snippets. |
Use for identifiers, literals, and short expressions. |
<pre>{@code ... }</pre> |
Code blocks. |
Preserve formatting without HTML escaping surprises. |
@since |
Version or release introduction. |
Use only when the project tracks API versions. |
@version |
Member or type version. |
Use only if the project already maintains version tags. |
@author |
Author attribution. |
Use only if the project convention already uses it. |
Content patterns
| API shape |
Document |
| Mutator |
Side effects, validation, idempotency, and thread-safety expectations. |
| Accessor |
Units, nullability, caching, and whether returned collections are mutable. |
| Factory |
Ownership, lifecycle, default values, and failure modes. |
| Async or callback API |
Execution thread, ordering, cancellation, and exception propagation. |
| Collection-returning method |
Ordering, duplicates, mutability, and empty-result behavior. |
| Security-sensitive method |
Required permissions, input trust boundary, and logging constraints. |
Examples
Good
/**
* Returns the active customer names in display order.
*
* @param regionCode the ISO region code used to filter customers
* @return immutable list of active customer names, never {@code null}
* @throws IllegalArgumentException if {@code regionCode} is blank
*/
List<String> findActiveCustomerNames(String regionCode);
Bad
/**
* findActiveCustomerNames method.
* @param regionCode Region code.
* @return list.
*/
List<String> findActiveCustomerNames(String regionCode);
Gotchas
- Do not repeat the signature: explain the contract, not that
getName gets a name.
- Do not use
{@inheritDoc} when behavior changes: callers need the subclass-specific differences.
- Do not add
@return to void methods: document side effects in prose instead.
- Do not introduce
@author, @version, or @since inconsistently: follow existing project convention.
Output template
## Java documentation result
**Status:** documented | needs project decision | blocked
**Scope:** `<files or selection>`
| Element | Action | Evidence |
| --- | --- | --- |
| `<class or member>` | added/updated/reviewed | `<tags and contract details>` |
**Validation**
- Summary sentences end with periods: pass/fail
- Required tags present: pass/fail
- Project conventions preserved: pass/fail
Quality gate
1---2name: java-docs3description: Write and review Java Javadoc comments for public, protected, generic, deprecated, and complex members. Use this skill when the user asks for Java documentation, Javadoc best practices, missing comments, API docs, or documentation cleanup in Java code.4---56<!-- Generated from harness/github-copilot/skills/java-docs/SKILL.md by harness/claude-code/scripts/convert_from_copilot.py. Edit the source, not this file. -->78# Java documentation910Add or improve Javadoc so Java APIs communicate behavior, parameters, return values, exceptions, inheritance, generics, deprecations, and examples without restating obvious implementation details.1112## When to invoke1314- "Add Javadoc to these Java classes."15- "Review this Java documentation for best practices."16- "Document public and protected methods with Javadoc."17- "Fix missing `@param`, `@return`, or `@throws` tags."1819## Documentation coverage2021| Element | Requirement | Notes |22| --- | --- | --- |23| Public types and members | Document with Javadoc comments. | Treat this as mandatory API documentation. |24| Protected members | Document with Javadoc comments. | Subclasses depend on the contract. |25| Package-private and private members | Document when complex or not self-explanatory. | Prefer clear code over comments for obvious internals. |26| Generic type parameters | Use `@param <T>`. | Describe what the type represents, not its Java syntax. |27| Exceptions | Use `@throws` or `@exception`. | Document conditions that callers can act on. |28| Deprecations | Use `@deprecated` and provide an alternative. | Pair with the Java `@Deprecated` annotation when changing code. |2930## Javadoc tag rules3132| Tag or construct | Use | Style rule |33| --- | --- | --- |34| Summary sentence | First sentence of every Javadoc comment. | Concise overview ending with a period. |35| `@param` | Method parameters. | Description starts with a lowercase letter and does not end with a period. |36| `@return` | Non-void return values. | Explain meaning, units, nullability, and special cases. |37| `@throws` / `@exception` | Exceptions thrown by methods. | Prefer `@throws`; include the triggering condition. |38| `@see` | References to other types or members. | Use for related APIs, not generic external reading. |39| `{@inheritDoc}` | Inherit base-class or interface documentation. | Use unless behavior materially changes; document differences when it does. |40| `{@code}` | Inline code snippets. | Use for identifiers, literals, and short expressions. |41| `<pre>{@code ... }</pre>` | Code blocks. | Preserve formatting without HTML escaping surprises. |42| `@since` | Version or release introduction. | Use only when the project tracks API versions. |43| `@version` | Member or type version. | Use only if the project already maintains version tags. |44| `@author` | Author attribution. | Use only if the project convention already uses it. |4546## Content patterns4748| API shape | Document |49| --- | --- |50| Mutator | Side effects, validation, idempotency, and thread-safety expectations. |51| Accessor | Units, nullability, caching, and whether returned collections are mutable. |52| Factory | Ownership, lifecycle, default values, and failure modes. |53| Async or callback API | Execution thread, ordering, cancellation, and exception propagation. |54| Collection-returning method | Ordering, duplicates, mutability, and empty-result behavior. |55| Security-sensitive method | Required permissions, input trust boundary, and logging constraints. |5657## Examples5859### Good6061```java62/**63 * Returns the active customer names in display order.64 *65 * @param regionCode the ISO region code used to filter customers66 * @return immutable list of active customer names, never {@code null}67 * @throws IllegalArgumentException if {@code regionCode} is blank68 */69List<String> findActiveCustomerNames(String regionCode);70```7172### Bad7374```java75/**76 * findActiveCustomerNames method.77 * @param regionCode Region code.78 * @return list.79 */80List<String> findActiveCustomerNames(String regionCode);81```8283## Gotchas8485- **Do not repeat the signature**: explain the contract, not that `getName` gets a name.86- **Do not use `{@inheritDoc}` when behavior changes**: callers need the subclass-specific differences.87- **Do not add `@return` to `void` methods**: document side effects in prose instead.88- **Do not introduce `@author`, `@version`, or `@since` inconsistently**: follow existing project convention.8990## Output template9192```markdown93## Java documentation result9495**Status:** documented | needs project decision | blocked96**Scope:** `<files or selection>`9798| Element | Action | Evidence |99| --- | --- | --- |100| `<class or member>` | added/updated/reviewed | `<tags and contract details>` |101102**Validation**103- Summary sentences end with periods: pass/fail104- Required tags present: pass/fail105- Project conventions preserved: pass/fail106```107108## Quality gate109110- [ ] Public and protected Java types and members have meaningful Javadoc comments.111- [ ] Complex package-private or private members are documented when code alone is not self-explanatory.112- [ ] The first sentence is a concise summary and ends with a period.113- [ ] Every parameter has `@param`; generic parameters use `@param <T>`.114- [ ] Non-void methods have `@return` when the return contract is not obvious.115- [ ] Exceptions are documented with `@throws` or `@exception` where callers need to know failure conditions.116- [ ] Inline code uses `{@code}` and blocks use `<pre>{@code ... }</pre>`.117- [ ] `@deprecated`, `@since`, `@version`, `@author`, and `@see` follow existing project conventions.
paulasilvatech