Notre avis

Cette compétence fournit des normes pour la rédaction de documentation JavaDoc dans les projets Java, incluant les motifs pour les classes, méthodes, exemples de code et références d'erreur.

Points forts

Structure claire avec directives étape par étape
Couverture complète des classes, méthodes, exemples et erreurs
Ordre des balises standardisé garantissant la cohérence
Références vers des fichiers de normes supplémentaires pour une personnalisation

Limites

Nécessite que les fichiers de normes externes (javadoc-core.md, etc.) existent
Spécifique à Java et JavaDoc, non applicable à d'autres langages
Peut être verbeux pour des projets très simples

Quand l'utiliser

Utilisez cette compétence lors de l'écriture ou de la révision de JavaDoc pour garantir la cohérence et la qualité dans une base de code Java.

Quand l'éviter

Ne convient pas aux projets utilisant d'autres formats de documentation (Markdown, par exemple) ou pour des bases de code très petites avec des besoins de documentation minimaux.

Exemples

Add class documentation

Generate JavaDoc class documentation for the TokenValidator class following the JavaDoc skill standards. Include @since, @see, and a description of its purpose.

Add method documentation with tags

Add JavaDoc method documentation to the validate method, including @param, @return, and @throws tags according to the standard tag order.

Add code example with @snippet

Add a code example using the @snippet tag to the parse method documentation showing how to use the ConfigParser.

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 patterns
pm-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 |

Standards JavaDoc

Recommandé pour