java-docs — скилл для GitHub Copilot: Javadoc и установка
Помогает документировать Java-типы через Javadoc по стилю проекта и проверять комментарии. Нужен при добавлении или правке API-документации.
npx skills add github/awesome-copilot --skill java-docs -a claude-codeЧто делает java-docs
Скилл направляет GitHub Copilot при подготовке Javadoc для Java-типов. Он предлагает сначала сверить реализацию, вызовы и тесты, чтобы не приписать коду непроверенные свойства, исключения или правила работы с null.
Он сохраняет принятый в проекте язык и форму комментариев, не переписывает существующую документацию без запроса и учитывает уровень JDK. Для примеров доступны {@code ... }, а на JDK 18+ — {@snippet}; комментарии Markdown с /// допустимы на JDK 23+ при соответствующей настройке проекта.
После правок скилл предлагает запустить mvn -q javadoc:javadoc, ./gradlew javadoc или javadoc -Xdoclint:all. Его стоит ставить командам, которые хотят держать Javadoc в проверяемом состоянии; для разовой заметки в коде он избыточен.
Какие задачи решает
- добавить Javadoc к Java-типу по фактической реализации
- сохранить стиль комментариев, принятый в проекте
- выбрать формат примера под версию JDK
- исправить предупреждения doclint в Javadoc
- оформить
@deprecatedс причиной и заменой
Примеры запросов агенту
- «Добавь Javadoc для этого Java-типа и проверь вызовы с тестами.»
- «Обнови комментарий API, не меняя стиль существующей документации.»
- «Проверь Javadoc командой `mvn -q javadoc:javadoc` и исправь новые предупреждения.»
Как установить java-docs
1Через Skills CLI (Vercel)
npx skills add github/awesome-copilot --skill java-docs -a claude-code2Вручную: положить файлы
~/.claude/skills/java-docs/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/java-docs/
Вручную: положить файлы
.agents/skills/java-docs/SKILL.mdДля всех проектов — ~/.agents/skills/
Вручную: положить файлы
.cursor/skills/java-docs/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1Через Skills CLI (Vercel)
npx skills add github/awesome-copilot --skill java-docs2GitHub CLI
gh skill install github/awesome-copilot java-docs3Вручную: положить файлы
.github/skills/java-docs/SKILL.mdКомандой платформы
gemini skills install https://github.com/github/awesome-copilot --path skills/java-docsВручную: положить файлы
.devin/skills/java-docs/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Claude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
Похожие
Вопросы о java-docs
Как установить java-docs в GitHub Copilot?
Выполните npx skills add github/awesome-copilot --skill java-docs или gh skill install github/awesome-copilot java-docs. Скилл будет размещён в .github/skills/java-docs/SKILL.md.
Что делает java-docs?
Скилл задаёт правила подготовки Javadoc для Java-типов: опираться на код и тесты, соблюдать стиль проекта и проверять итоговую документацию через Javadoc-инструменты.
Какие форматы примеров использует java-docs?
Для любого JDK подходит {@code ... }. На JDK 18+ можно применять {@snippet}, а Markdown-комментарии /// предусмотрены для JDK 23+ при поддержке в проекте.
Исходный текст
SKILL.md · MIT
---
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.
© github · MIT · github/awesome-copilot
