cuioss/javadoc

JavaDoc Skill

REFERENCE MODE: This skill provides reference material. Load specific standards on-demand based on current task.

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

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

• plan-marshall:ref-code-quality - Language-agnostic code quality and documentation principles
• pm-dev-java:java-core - Core Java patterns
• pm-dev-java:java-null-safety - Null annotations in docs

Templates

JavaDoc class and method — reference templates for documentation structure:

Read: templates/javadoc-class.java.tmpl

Contains both class-level and method-level JavaDoc patterns with all standard tags.

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 |