cui-javadoc

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)