Java Docs

Name: Java Docs
Author: github

github/awesome-copilot

10.3k installs
37.1k repo stars
Updated July 28, 2026
github/awesome-copilot

Best practices and conventions for writing Javadoc comments in Java source code to document types, methods, fields, and exceptions.

About

This skill teaches Java developers how to document code using Javadoc comments. It covers best practices for public, protected, and private members, including proper use of tags like @param, @return, @throws, @see, @deprecated, and @since. Developers use this when writing or reviewing Java libraries and APIs to ensure comprehensive, consistent documentation that can be parsed into HTML docs and improves code clarity.

Document public and protected members with Javadoc; encourage docs for complex package-private and private members
Use @param (lowercase, no period), @return, @throws, and @see tags correctly in method documentation
Use {@inheritDoc} to inherit docs from base classes unless major behavior changes require explicit differences
Format code snippets with {@code} for inline or <pre>{@code}</pre> for blocks within comments
Mark deprecated members with @deprecated tag and provide alternative; use @since and @version for versioning

Java Docs by the numbers

10,338 all-time installs (skills.sh)
+62 installs in the week ending Jul 28, 2026 (Skillselion tracking)
Ranked #42 of 1,901 Documentation skills by installs in the Skillselion catalog
Security screen: MEDIUM risk (skills.sh audit)
Data as of Jul 28, 2026 (Skillselion catalog sync)

At a glance

java-docs capabilities & compatibility

Use cases: documentation · code review

From the docs

What java-docs says it does

Public and protected members should be documented with Javadoc comments.

java-docs.md

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.

java-docs.md

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

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/github/awesome-copilot/java-docs.svg)](https://skillselion.com/skills/github/awesome-copilot/java-docs)

Installs	10.3k
repo stars	★ 37.1k
Security audit	3 / 3 scanners passed
Last updated	July 28, 2026
Repository	github/awesome-copilot ↗

What it does

Write and validate Javadoc comments for Java types, methods, and members following standard conventions.

Who is it for?

Java library and API developers, teams enforcing documentation standards, developers writing public or complex internal code.

Skip if: Projects not using Java, codebases not requiring API documentation, scripts or throwaway code.

When should I use this skill?

Writing or reviewing Java code with public or protected members; preparing code for library release; setting up documentation standards for a team.

What you get

Developers write clear, consistent Javadoc comments that follow standard conventions, enabling automated API documentation generation and improving code maintainability.

Well-formed Javadoc comments on public and protected members
Consistent use of @param, @return, @throws, @see tags
Proper formatting with {@code} and code blocks

By the numbers

Standard Javadoc tags: @param, @return, @throws, @see, @since, @version, @author, @deprecated, @inheritDoc, {@code}
Documentation scope: public and protected members required; package-private and private encouraged

Files

SKILL.mdMarkdownGitHub ↗

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.