AutoGineer
Generated banner for Java Docs
Generated logo for Java Docs

Java Docs

GitHubOfficialFirst committed by jduboisDistributed by GitHub

  • Skill
  • Guidelines
  • Software development
  • MIT
  • No issues found
Download ZIP

From the author

Ensure that Java types are documented with Javadoc comments and follow best practices for documentation.
— the description by jdubois

From the skill’s files

Taken from the skill’s own files (its description, section headings and stated usage). Not an AutoGineer summary, and not written by the author as one.

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

What it does

  • Principles
  • Conventions
  • Verify

When to use it

The skill’s files do not state this.

Advantages

The skill’s files do not state this.

Usage examples

The skill’s files do not state this.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/github/java-docs/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip java-docs.zip -d .agents/skills

Documentation by jdubois

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.

Files

SKILL.md

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.

Requirements and compatibility

Written for: GitHub Copilot

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

First committed by
GitHub avatar of jduboisjdubois
Publisher
GitHub (Official)
Distributed by
GitHub
Source
github/awesome-copilot · skills/java-docs · commit 797337f
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced
Contributors
jdubois

AutoGineer is not affiliated with or endorsed by jdubois or GitHub.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download java-docs.zip