170-java-documentation
npx machina-cli add skill jabrena/cursor-rules-java/170-java-documentation --openclawJava Documentation Generator with modular step-based configuration
Generate comprehensive Java project documentation through a modular, step-based interactive process that covers README.md, package-info.java, and Javadoc.
Core areas: README.md generation for single-module and multi-module Maven projects, package-info.java creation with basic/detailed/minimal documentation levels, Javadoc enhancement with comprehensive @param/@return/@throws tags, file handling strategies (overwrite/add/backup/skip), and final documentation validation with ./mvnw clean compile and ./mvnw javadoc:javadoc.
Prerequisites: Run ./mvnw validate or mvn validate before applying any documentation generation. If validation fails, stop immediately — do not proceed until all validation errors are resolved.
Multi-step scope: Step 1 assesses documentation preferences through targeted questions (README.md, package-info.java, Javadoc) to determine which subsequent steps to execute. Step 2 generates README.md files with software descriptions, build instructions, and optional sections based on code analysis — conditionally executed if selected. Step 3 generates package-info.java files for every package in src/main/java, with documentation depth matching the user's chosen level — conditionally executed if selected. Step 4 enhances Javadoc for public and protected APIs, adding missing @param, @return, @throws tags, and usage examples — conditionally executed if selected. Step 5 validates all generated documentation by compiling the project and running Javadoc generation, then produces a comprehensive summary of files created, modified, and skipped.
Before applying changes: Read the reference for detailed good/bad examples, constraints, and safeguards for each documentation generation pattern.
Reference
For detailed guidance, examples, and constraints, see references/170-java-documentation.md.
Source
git clone https://github.com/jabrena/cursor-rules-java/blob/main/skills/170-java-documentation/SKILL.mdView on GitHub Overview
Generates or improves Java project documentation via a modular, step-based workflow. It covers README.md, package-info.java, and enhanced Javadoc for both single-module and multi-module Maven projects, with safe file handling and pre-release validation.
How This Skill Works
The tool runs in five steps: assess documentation preferences (which docs to generate and how deep the content should be), generate README.md based on code analysis, create package-info.java in every package under src/main/java with the chosen depth, enhance Javadoc by adding missing @param/@return/@throws and usage examples, then validate the entire output by running Maven validation, clean compile, and javadoc generation, finishing with a summary of changes.
When to Use It
- When starting a new Java project and you need a solid README plus initial Javadoc structure.
- When converting a multi-module Maven project to include consistent README, package-info, and Javadoc across modules.
- When public APIs lack complete Javadoc coverage (missing @param/@return/@throws) and you want automated enhancement.
- When migrating from manual documentation to a modular, interactive documentation workflow.
- When you must validate all generated docs by compiling the project and generating Javadoc before release.
Quick Start
- Step 1: Ensure prerequisites are met by running mvn validate and fixing any errors.
- Step 2: Answer Step 1 prompts to select which docs to generate (README, package-info, Javadoc) and the desired depth and file handling.
- Step 3: Run the modular steps to generate/docs, then execute ./mvnw clean compile and ./mvnw javadoc:javadoc and review the summary.
Best Practices
- Define the exact documentation scope in Step 1 to prevent scope creep (README, package-info, Javadoc).
- Always run mvn validate first and halt on errors before applying changes.
- Choose an appropriate documentation depth level for package-info.java (basic, minimal, detailed) and Javadoc.
- Select a file handling strategy (overwrite/add/backup/skip) that preserves important history.
- After generation, run ./mvnw clean compile and ./mvnw javadoc:javadoc and review the produced files.
Example Use Cases
- Document a new single-module Java library with a comprehensive README and initial Javadoc tags.
- Generate README and package-info for a multi-module Maven project to ensure consistent docs across modules.
- Improve Javadoc for public APIs across modules by adding missing @param/@return/@throws tags.
- Create package-info.java files for all packages under src/main/java with package-level docs.
- Validate the final documentation output by running Maven validation, compilation, and Javadoc generation before release.
