Which members should be documented?

Public and protected members should be documented with Javadoc; it is encouraged to document package-private and private members as well, especially if they are complex or not self-explanatory.

How should the first sentence be written?

The first sentence of the Javadoc should be a concise summary description that ends with a period.

What tags and formatting should I use?

Use @param for parameters (description starts lowercase, no trailing period), @return for returns, and @throws for exceptions. Include @see for references and {@inheritDoc} when appropriate; use {@code ...} for inline code and {@code ...} for code blocks. Include @since, @version, @author, and @deprecated as applicable.

java-docs

npx machina-cli add skill github/awesome-copilot/java-docs --openclaw

Files (1)

SKILL.md

1.4 KB

Java Documentation (Javadoc) Best Practices

Public and protected members should be documented with Javadoc comments.
It is encouraged to document package-private and private members as well, especially if they are complex or not self-explanatory.
The first sentence of the Javadoc comment is the summary description. It should be a concise overview of what the method does and end with a period.
Use @param for method parameters. The description starts with a lowercase letter and does not end with a period.
Use @return for method return values.
Use @throws or @exception to document exceptions thrown by methods.
Use @see for references to other types or members.
Use {@inheritDoc} to inherit documentation from base classes or interfaces.
- Unless there is major behavior change, in which case you should document the differences.
Use @param <T> for type parameters in generic types or methods.
Use {@code} for inline code snippets.
Use <pre>{@code ... }</pre> for code blocks.
Use @since to indicate when the feature was introduced (e.g., version number).
Use @version to specify the version of the member.
Use @author to specify the author of the code.
Use @deprecated to mark a member as deprecated and provide an alternative.

Source

git clone https://github.com/github/awesome-copilot/blob/main/plugins/java-development/skills/java-docs/SKILL.mdView on GitHub

Overview

This skill codifies Javadoc best practices for documenting Java types and members. It covers public and protected members, and encourages documenting package-private and private members when they are complex or not self-explanatory, to ensure clear and maintainable APIs.

How This Skill Works

The approach outlines required Javadoc tags and formatting, then guides how to apply them to code comments during development and reviews. It emphasizes concise summaries, proper @param/@return/@throws usage, and references like @see or {@inheritDoc} to maintain consistent documentation across classes and hierarchies.

When to Use It

When designing a public API class or interface that others will consume
When documenting methods that have parameters and return values
When methods can throw exceptions (checked or runtime) that callers should handle
When using generics or type parameters that require explanation
When introducing new features or deprecating existing methods or classes

Quick Start

Step 1: Identify public/protected API surface to document; consider private helpers if needed
Step 2: Write a concise summary sentence and add relevant @param, @return, and @throws tags
Step 3: Add @see, {@inheritDoc}, and code examples using {@code ...} or <pre>{@code ...}</pre> as appropriate

Best Practices

Document public and protected members with Javadoc; consider private members if they are non-trivial or complex
Start each Javadoc with a concise summary sentence that ends with a period
Use @param for method parameters (description starts with a lowercase letter and does not end with a period); use @return and @throws/@exception accordingly
Include @see references for related types and {@inheritDoc} where appropriate, noting differences if behavior changes
Leverage inline code snippets with {@code ...} and code blocks with <pre>{@code ...}</pre>; add @since/@version/@author/@deprecated as applicable

Example Use Cases

Public API method documented with @param and @return to describe inputs and outputs
Method that documents potential exceptions using @throws with a concise explanation
Private helper method documented when its behavior is not self-explanatory
Class-level @see references to related types to aid discoverability
Deprecated method annotated with @deprecated and an alternative usage

Frequently Asked Questions

Add this skill to your agents