Java Docs
Apply consistent Javadoc to Java public APIs so solo builders ship readable, review-ready API docs without guessing tag conventions.
Overview
java-docs is an agent skill most often used in Build (also Ship review) that enforces Javadoc comment structure and tag conventions on Java types.
Install
npx skills add https://github.com/github/awesome-copilot --skill java-docsWhat is this skill?
- Requires Javadoc on public and protected members; encourages docs on complex package-private/private code
- Summary sentence rules plus @param, @return, @throws/@exception, @see, and {@inheritDoc} guidance
- Generic @param <T>, inline {@code}, and <pre>{@code}</pre> block formatting
- Metadata tags: @since, @version, @author, and @deprecated with migration notes
- 15+ concrete Javadoc formatting and inheritance rules from the skill checklist
- 15+ Javadoc tag and formatting rules in the skill checklist
Adoption & trust: 9.8k installs on skills.sh; 34.6k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your Java APIs ship with missing, inconsistent, or wrongly formatted Javadoc that breaks generated docs and slows code review.
Who is it for?
Solo builders writing or refactoring Java libraries, services, or shared modules where API comments must match team and JavaDoc tooling expectations.
Skip if: Non-Java codebases, projects that rely solely on external doc generators with zero hand-written member comments, or teams that forbid inline documentation.
When should I use this skill?
Ensure Java types are documented with Javadoc comments and follow documentation best practices.
What do I get? / Deliverables
Public and protected members gain concise, tag-correct Javadoc aligned with standard Java documentation practice.
- Javadoc blocks on classes, methods, and fields matching the skill’s tag rules
- Deprecation and cross-reference text suitable for JavaDoc HTML output
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Documentation is authored while implementing Java types—the canonical shelf is Build → docs. The skill is entirely about Javadoc structure and tags on classes and members, not runtime behavior or tests.
Where it fits
Document a new REST DTO and service interface before merging feature work.
Tighten Javadoc on a PR where reviewers flagged missing @throws and vague summaries.
Refresh @deprecated notes when sunsetting an internal helper used by multiple modules.
How it compares
Structured Javadoc rules in one skill beat ad-hoc 'add comments' prompts that omit @throws, {@inheritDoc}, and deprecation wording.
Common Questions / FAQ
Who is java-docs for?
Indie and solo developers on JVM stacks who want an agent to apply standard Javadoc patterns while they implement or polish APIs.
When should I use java-docs?
During Build when documenting new types; before Ship review on API-changing PRs; when fixing review feedback on missing @param, @return, or @deprecated text.
Is java-docs safe to install?
It is prose guidance only—no shell or network access by itself. Review the Security Audits panel on this Prism page before enabling it in your agent.
SKILL.md
READMESKILL.md - Java Docs
# 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.