Our review
This skill defines JavaDoc documentation standards for classes, methods, and code examples in Java projects.
Strengths
- Enforces consistent JavaDoc documentation rules.
- Covers class, method, and code example documentation.
- Includes error troubleshooting for JavaDoc warnings.
Limitations
- Requires the standard files to be present in the project.
- Does not cover automatic documentation generation.
Use this skill when you need to document Java code following standard JavaDoc conventions.
Do not use it for non-Java languages or for projects using alternative documentation tools.
Security analysis
CautionThe skill content only performs reads of documentation files and does not contain any destructive or exfiltrating commands. However, the allowed-tools metadata includes Bash, which could enable arbitrary command execution if the agent is subsequently prompted outside the skill's scope. Since Bash is a powerful tool and is not required for JavaDoc documentation tasks, its inclusion elevates the risk from minimal to caution.
- •Bash is declared as an allowed tool but is not used by the skill's workflow, unnecessarily increasing the agent's potential attack surface.
Examples
Add JavaDoc to the TokenValidator class following the project's JavaDoc standards.Write JavaDoc for the validate method including @param, @return, and @throws tags.Add a @snippet code example to the parse method documentation.name: javadoc description: JavaDoc documentation standards including class, method, and code example patterns allowed-tools: [Read, Edit, Write, Bash, Grep, Glob]
JavaDoc Skill
EXECUTION MODE: You are now executing this skill. DO NOT explain or summarize these instructions to the user. IMMEDIATELY begin the workflow below based on the task context.
JavaDoc documentation standards for Java projects. This skill covers class documentation, method documentation, code examples, and error references.
Prerequisites
This skill applies to all Java projects using standard JavaDoc.
Workflow
Step 1: Load Core Standards
CRITICAL: Load this standard for any JavaDoc work.
Read: standards/javadoc-core.md
This provides foundational rules for:
- Mandatory documentation requirements
- Clarity, completeness, and consistency principles
- Tag ordering standards
Step 2: Load Specific Standards (As Needed)
Class Documentation (load for class-level docs):
Read: standards/javadoc-class-documentation.md
Use when: Documenting classes, interfaces, enums, or annotations.
Method Documentation (load for method-level docs):
Read: standards/javadoc-method-documentation.md
Use when: Documenting methods, including parameters, returns, and exceptions.
Code Examples (load for example snippets):
Read: standards/javadoc-code-examples.md
Use when: Adding code examples to documentation using @snippet or @code.
Error Reference (load for troubleshooting):
Read: standards/javadoc-error-reference.md
Use when: Fixing JavaDoc errors or warnings.
Key Rules Summary
Class Documentation
/**
* Validates JWT tokens against configured issuer and signing keys.
*
* <p>This validator supports both HMAC and RSA algorithms with
* configurable clock skew tolerance for distributed systems.
*
* @since 1.0
* @see TokenConfig
*/
@ApplicationScoped
public class TokenValidator { }
Method Documentation
/**
* Validates the JWT token signature and expiration time.
*
* @param token the JWT token to validate, must not be null
* @return validation result containing status and error messages
* @throws IllegalArgumentException if token is null or empty
*/
public ValidationResult validate(String token) { }
Code Examples
/**
* Parses JSON configuration from a file.
*
* <p>Example usage:
* {@snippet :
* Config config = ConfigParser.parse("config.json");
* String value = config.get("key");
* }
*/
public Config parse(String filename) { }
Tag Order
/**
* Description.
*
* @param name description
* @return description
* @throws ExceptionType description
* @since version
* @see reference
* @deprecated reason
*/
Related Skills
pm-dev-java:java-core- Core Java patternspm-dev-java:java-null-safety- Null annotations in docs
Standards Reference
| Standard | Purpose | |----------|---------| | javadoc-core.md | Core principles and mandatory requirements | | javadoc-class-documentation.md | Class-level documentation | | javadoc-method-documentation.md | Method-level documentation | | javadoc-code-examples.md | @snippet and @code patterns | | javadoc-error-reference.md | Error troubleshooting |
API Documentation Generator
Documentation
Automatically generates OpenAPI/Swagger API documentation.
Technical Writer
Documentation
Writes clear technical documentation following top style guides.
Pivot Decision Framework
Documentation
Documents a strategic pivot or persevere decision with evidence, analysis, and rationale. Use when evaluating whether to change direction on a product, feature, or strategy based on market feedback.