Java Javadoc

This documentation was generated with the assistance of AI. Please report any inaccuracies.

Audit given Java class(es) — and the package(s) they live in — for complete Javadoc coverage, generate whatever is missing grounded in the actual code and current changes, then run the project’s Javadoc build goal to confirm the result is well-formed. Unlike the other skills in this group, iru-java-javadoc does modify files: it writes Javadoc comments and, where needed, creates package-info.java — but it never changes behavior, signatures, or non-Javadoc code, and test classes are exempt from the documentation requirement.

Purpose

iru-java-javadoc closes documentation gaps without assuming a fixed house style: it first discovers this project’s own Javadoc bar (contributor guide, Checkstyle Javadoc* module scopes, maven-javadoc-plugin <show>, or observed practice in nearby classes) and phrasing conventions, then audits every type/field/constructor/method/ enum constant/nested type in scope, fills in what’s missing, ensures each touched package has a proper package-info.java, and proves the result actually builds via the project’s own Javadoc goal — rather than generating generic, possibly non-conforming comments.

Purpose group

Java Development Tooling

Invocation

/iru-java-javadoc
/iru-java-javadoc <ClassName1,ClassName2,...>

Inputs

Argument Required Description Default

Argument	Required	Description	Default
`ClassName1,ClassName2,…`	No	Comma-separated class names or file paths to audit. A simple class name is located via `find`/`grep` across the whole project (main and test source roots). Any resolved file living under the test source root (`src/test/java` by convention) is dropped from the audited/generated scope and called out in the final report, since test classes carry no Javadoc requirement here.	None — defaults to every main-source `.java` file touched by uncommitted changes plus commits on the current branch not yet on the base branch (same approach as the `iru-update-docs` skill). If that default scope is empty, the skill tells the user there’s nothing to document and stops.

ClassName1,ClassName2,…

Comma-separated class names or file paths to audit. A simple class name is located via find/grep across the whole project (main and test source roots). Any resolved file living under the test source root (src/test/java by convention) is dropped from the audited/generated scope and called out in the final report, since test classes carry no Javadoc requirement here.

None — defaults to every main-source .java file touched by uncommitted changes plus commits on the current branch not yet on the base branch (same approach as the iru-update-docs skill). If that default scope is empty, the skill tells the user there’s nothing to document and stops.

Outputs

Edits (via the Edit tool) to the in-scope class files, adding or completing Javadoc comments — no logic, signatures, formatting outside the added comments, or member ordering is changed.
A new or completed package-info.java for every touched package that was missing one or had only a placeholder/absent package doc comment.
A confirmed, warning-free build of the project’s Javadoc goal (mvn javadoc:jar, or a discovered equivalent) scoped to the files touched.
A plain-text report: per class, how many members were already documented vs. gaps found and filled (named); per package, whether its package-info.java was already complete, extended, or newly created; any test-class argument excluded; any out-of-scope pre-existing Javadoc warning surfaced as a separate follow-up note.
No static-analysis fixes outside Javadoc, and no test changes — those are left to other skills.

Execution flow

flowchart TD A["Start /java-javadoc\n(optional class names or file paths)"] --> B{Argument given?} B -- yes --> C["Resolve each to a file;\ndrop test-source files from scope"] B -- no --> D["Scope to files touched by uncommitted\nchanges + branch commits not on base"] C --> E{Scope empty?} D --> E E -- yes --> F["Tell user: nothing to document, stop"] E -- no --> G["Derive distinct packages\nfrom in-scope files"] G --> H["Discover this project's Javadoc bar:\ncontributor guide, Checkstyle config,\njavadoc-plugin <show>, or observed practice"] H --> I["Skim existing documented classes\nfor phrasing conventions"] I --> J["Audit each in-scope class: type, fields,\nconstructors, methods, enum constants,\nnested types"] J --> K["Record every gap: member,\nwhat's missing, visibility"] K --> L["Check each touched package's\npackage-info.java"] L --> M["Create/complete package-info.java\nwhere missing or placeholder-only"] M --> N["Generate missing Javadoc grounded in\nimplementation + git diff/log + Step 2 conventions"] N --> O["Apply edits with the Edit tool"] O --> P["Run mvn javadoc:jar (or discovered\nequivalent) to verify the build"] P --> Q{Fails or warns\non in-scope files?} Q -- yes --> R["Fix offending comments,\nre-run until clean"] Q -- no --> S["Report: per-class gaps filled,\nper-package package-info status,\nbuild result"] R --> S

Dependencies

Invokes

None — iru-java-javadoc is a leaf skill; it only runs Maven commands, reads/edits Java source, and reports, it does not call any other skill in this catalog.

Invoked by

Java Code One Task Group — Step 3, once per task group’s bucket, via the iru-gate-runner agent, to update Javadoc for every class the bucket touched and confirm the Javadoc build passes.

Related agents

iru-gate-runner — iru-java-code-one-task-group (see Java Code One Task Group) always invokes this skill from inside a iru-gate-runner sub-agent it spawns, not inline.

Source

SKILL.md on GitHub — the file this page was generated from.