skills.rest
cuioss
cuiossCOMMUNITY
Explore all skills by this author →
GitHub

cui-javadoc

Enforce JavaDoc documentation standards across CUI Java codebases.

1|Updated Feb 3, 2025
Search Tags:#code quality#documentation#technical writing#Java#null safety#JavaDoc#API documentation
One-click install
npx skills add https://github.com/cuioss/cui-llm-rules --skill cui-javadoc
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: cui-javadoc
Source: https://github.com/cuioss/cui-llm-rules/tree/main/claude/marketplace/skills/cui-javadoc
Command: npx skills add https://github.com/cuioss/cui-llm-rules --skill cui-javadoc

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Poorly documented or inconsistent JavaDoc makes APIs difficult to understand and use, leading to developer frustration and integration errors. This Skill provides a comprehensive set of standards for writing high-quality JavaDoc, ensuring clarity, completeness, and consistency across all CUI Java projects, making your APIs easier to consume.

Core Features & Use Cases

  • Standardized Documentation: Enforces core principles like clarity, completeness, and consistency, avoiding "stating the obvious" and focusing on behavior.
  • Class & Method Documentation: Guides the documentation of packages, classes, interfaces, enums, annotations, and all public/protected methods with detailed parameter, return, and exception descriptions.
  • Rich Code Examples: Provides patterns for inline code, multi-line code blocks, cross-references, and HTML formatting (tables, lists) to enhance readability.
  • Null-Safety Integration: Guides documentation for @NullMarked and @Nullable annotations, clarifying null-safety contracts.
  • Use Case: When developing a new Java library or API, use this skill to ensure every public class and method is meticulously documented with clear purpose statements, usage examples, and precise null-safety contracts, making your API a joy to use and reducing support overhead.

Quick Start

Document a Class

  1. Add class-level JavaDoc with purpose and behavior
  2. Document thread-safety if applicable
  3. Add usage example for complex classes
  4. Document all public methods
  5. Include parameter constraints and return guarantees
  6. Document all exceptions
  7. Add @see links to related classes
  8. Add @since tag for version
  9. Verify: mvn javadoc:javadoc

Add Code Examples

  1. Write complete, compilable examples
  2. Use <pre><code class="language-java"> blocks
  3. Include typical usage scenarios
  4. Show error handling if applicable
  5. Verify examples in unit tests
  6. Keep examples concise (< 10 lines preferred)

Frequently Asked Questions about cui-javadoc

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I document Java methods with JavaDoc to ensure clarity and completeness?▼

Document Java methods by writing clear purpose statements, adding @param tags for each parameter with constraints, @return tags describing the result, and @throws tags for exceptions. Include null-safety contracts using @NullMarked or @Nullable annotations, and add @see links to related classes. Use concise language focused on behavior, not restating obvious details.

What are JavaDoc standards for public classes and interfaces in Java projects?▼

JavaDoc standards require documenting all public and protected classes, interfaces, enums, and annotations with purpose statements, behavior descriptions, and thread-safety notes where applicable. Add usage examples for complex classes, document all public methods with parameters and exceptions, include @since tags for version tracking, and use @see cross-references to related types.

How do I add code examples to JavaDoc documentation?▼

Add code examples using `<pre><code class="language-java">` blocks with complete, compilable code snippets under 10 lines. Include typical usage scenarios and error handling where applicable. Verify examples compile in unit tests. Examples should demonstrate practical usage patterns and show how to interact with the API.

Can I validate JavaDoc compliance across my entire Java codebase?▼

Yes, validate JavaDoc compliance by running `mvn javadoc:javadoc` to check tag usage (@param, @return, @throws, @see, @since, @deprecated), cross-references, HTML formatting, and documentation completeness. This ensures consistent standards across all public classes, methods, fields, constructors, and packages in your CUI Java project.

What's the best way to document null-safety contracts in JavaDoc?▼

Document null-safety by clarifying @NullMarked and @Nullable annotations in method and field documentation. Specify in @param tags which parameters accept null values and which do not. In @return tags, state whether the method can return null. This ensures developers understand your API's null-safety guarantees.

Why is consistent JavaDoc documentation important for Java APIs?▼

Consistent JavaDoc prevents developer frustration by making APIs clear and easy to understand. Well-documented APIs reduce integration errors, support overhead, and improve code maintainability. Standardized documentation ensures every public class and method communicates its purpose, behavior, parameters, return values, and exceptions consistently.

Related Skills

Explore More Software Engineering Skills→
alexjcmalexjcm

documenting-java-code

Generate concise JavaDocs for classes, constructors, and public methods.

Community
Intermediate
JongsixJongsix

moai-docs-generation

Generate technical documentation from source code and API definitions.

Community
Advanced
PyroxinPyroxin
8

java-programmer

Guide Java development with mandatory tooling, JUnit testing, and Javadoc standards.

Community
Advanced
kssuminkssumin

api-docs-reference

Generate an OpenAPI 3 specification from Spring REST Docs.

Community
Intermediate