使い方
- インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
- 必要なツール、認証情報、対応環境を原文で確認します。
- 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/github/awesome-copilot --skill java-docs開始前の確認
- 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
- スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
リポジトリの原文
見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。
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
@sinceonly with the real version in which the API was introduced;@deprecatedwith a reason and replacement, together with@Deprecated.@authorand@versiononly 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 insnippet-files/(preferred for examples;javadocdoes 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// @replacemarkup 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 filesjavadoc -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.
