java-docs

bởi github

Các phương pháp hay nhất về Javadoc để ghi chú các kiểu, phương thức và thành viên Java. Các thành viên public và protected yêu cầu chú thích Javadoc; các thành viên package-private và private được khuyến khích, đặc biệt đối với mã phức tạp. Sử dụng các thẻ tiêu chuẩn: @param cho tham số, @return cho giá trị trả về, @throws cho ngoại lệ, @see cho tham chiếu chéo và @since cho theo dõi phiên bản. Câu đầu tiên đóng vai trò là mô tả tóm tắt và nên kết thúc bằng dấu chấm; mô tả tham số bắt đầu bằng chữ thường và không có dấu chấm. Sử dụng...

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

Tải ZIP GitHub

41k

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.