java-docs

github/awesome-copilot

Ensure Java types are documented with Javadoc comments following best practices.

What is java-docs?

This skill enforces Javadoc documentation standards for Java code. Use it to verify that public, protected, and other Java members include proper Javadoc comments with appropriate tags and follow established documentation conventions.

Validates that public and protected members have Javadoc comments
Enforces proper Javadoc tag usage (@param, @return, @throws, @see, etc.)
Checks that summary descriptions are concise and properly formatted
Ensures type parameters and generic types are documented with @param <T>
Verifies exception documentation with @throws or @exception tags
Promotes documentation of package-private and private members for complex code

How to install java-docs

npx skills add https://github.com/github/awesome-copilot --skill java-docs

Claude Code

Cursor

Windsurf

Cline

How to use java-docs

1.Review the Java types and members that need documentation
2.Add Javadoc comments to public and protected members using /** */ syntax
3.Include a concise summary sentence ending with a period as the first line
4.Add @param tags for each method parameter with lowercase descriptions
5.Add @return tags for method return values
6.Add @throws or @exception tags for exceptions the method may throw
7.Use @see for cross-references to related types or members
8.Apply {@inheritDoc} to inherit documentation from base classes unless behavior differs significantly

Use cases

Good for

Adding Javadoc to newly created Java classes and methods before code review
Auditing existing Java codebases to identify undocumented public APIs
Ensuring consistent documentation standards across a team's Java projects
Documenting generic types and complex methods with proper @param and @return tags
Marking deprecated methods and providing migration guidance with @deprecated

Who it's for

Java developers
Development teams with documentation standards
Code reviewers enforcing API documentation
Maintainers of open-source Java libraries

java-docs FAQ

Should I document private members?

It is encouraged to document package-private and private members, especially if they are complex or not self-explanatory. Public and protected members must be documented.

What should the first sentence of a Javadoc comment contain?

The first sentence is the summary description. It should be a concise overview of what the method does and must end with a period.

How do I document method parameters and return values?

Use @param for each method parameter with a lowercase description (no period), and @return for the return value description.

How do I handle documentation inheritance from base classes?

Use {@inheritDoc} to inherit documentation from base classes or interfaces. Only override it if there is a major behavior change, in which case document the differences.

What tags should I use for exceptions?

Use @throws or @exception tags to document exceptions thrown by methods.

Full instructions (SKILL.md)

Source of truth, from github/awesome-copilot.

name: java-docs description: 'Ensure that Java types are documented with Javadoc comments and follow best practices for documentation.'

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.

Surgical code refactoring to improve maintainability without changing behavior.

19k installsAudited