java-docs

작성자: github

Java 유형, 메서드 및 멤버 문서화를 위한 Javadoc 모범 사례. public 및 protected 멤버는 Javadoc 주석이 필요하며, package-private 및 private 멤버는 특히 복잡한 코드의 경우 권장됩니다. 표준 태그 사용: 매개변수에는 @param, 반환 값에는 @return, 예외에는 @throws, 상호 참조에는 @see, 버전 추적에는 @since. 첫 번째 문장은 요약 설명 역할을 하며 마침표로 끝나야 합니다. 매개변수 설명은 소문자로 시작하며 마침표 없이 작성합니다. 사용...

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

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.