java-docs

Vercel

All-time installs

10.8K

Ensure that Java types are documented with Javadoc comments and follow best practices for documentation.

Install

Other options

Summary

Javadoc best practices for documenting Java types, methods, and members.

Public and protected members require Javadoc comments; package-private and private members are encouraged, especially for complex code
Use standard tags: @param for parameters, @return for return values, @throws for exceptions, @see for cross-references, and @since for version tracking
First sentence serves as summary description and should end with a period; parameter descriptions start lowercase without periods
Use {@inheritDoc} to inherit documentation from base classes unless behavior changes significantly, and {@code} or <pre>{@code}</pre> for inline and block code snippets

Raw SKILL.md

2,087 bytes

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

# Java Documentation (Javadoc) Best Practices

## Principles

- Document only what the code actually does: read the implementation, callers and tests first. Never invent behaviour, thresholds, thread-safety, nullability or exceptions you have not verified; if unsure, leave it out or ask.
- Keep the existing documentation style of the project (language, tag order, comment form `/** */` vs `///`). Do not rewrite existing comments, or mass-document a codebase, unless the user asks; limit changes to the requested scope.
- Check the JDK level (`maven.compiler.release`, toolchain, `java -version`) before using newer features, and stay within it.

## Conventions

- `@since` only with the real version in which the API was introduced; `@deprecated` with a reason and replacement, together with `@Deprecated`.
- `@author` and `@version` only if the project already uses them.
- Code blocks, by JDK level:
  - Any JDK: `<pre>{@code ... }</pre>` (escape `@` at line start, balance braces).
  - JDK 18+: `{@snippet :  ... }` for inline code, or `{@snippet file="Example.java" region="demo"}` with files in `snippet-files/` (preferred for examples; `javadoc` does not compile or validate the snippet source, so compile and test the files in a separate build/test source set if you need that guarantee). Use `// @highlight substring="x"` and `// @replace` markup as needed.
  - JDK 23+ only (JEP 467): Markdown doc comments with `///`, using `[Type#member]` for links and fenced code blocks. Use them only if the project already does or the user asks, and the build runs a JDK 23+ `javadoc`.

## Verify

- Run `mvn -q javadoc:javadoc` (or `./gradlew javadoc`) and for single files `javadoc -Xdoclint:all -d target/javadoc-check <files>`; fix every warning/error you introduced (missing `@param`, bad HTML, unresolved `{@link}`, unknown tags).
- Report what was documented and the commands run; state any claims you could not verify from the code.

Security audits

SnykPASS

SocketPASS

Gen Agent Trust HubPASS