其他

java-docs

Name: java-docs
Author: github

github/awesome-copilot

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

安装命令

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

要点

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

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.

@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.