JSDoc Documentation Standards

JSDoc Documentation Standards

Overview

Provides JSDoc documentation standards for CUI JavaScript projects covering functions, classes, modules, types, and web components.

Standards Documents

• jsdoc-essentials.md - Core JSDoc syntax, required tags, ESLint setup, writing style
• jsdoc-patterns.md - Documentation patterns for all code element types with examples

What This Skill Provides

JSDoc Essentials

• ESLint plugin configuration and rules
• Documentation requirements (mandatory vs optional)
• Required and optional tags (@param, @returns, @throws, @example, @since, @see, @deprecated)
• Type annotations (basic types, unions, custom types)
• Writing style guidelines (present tense, active voice, clear language)
• Build integration (npm scripts, jsdoc.conf.json)
• Validation and common mistakes

Documentation Patterns

• Functions: Simple, async, complex with nested parameters
• Classes: Declaration, constructor, methods, inheritance
• Modules: File overview, exports, constants
• Types: Custom types (@typedef), callbacks, union/​literal types
• Web Components: Lit components, properties, events, CSS properties
• Quality Examples: Good vs bad documentation patterns

When to Activate

Use this skill when:

• Documenting JavaScript code (functions, classes, modules)
• Building web components (Lit or vanilla custom elements)
• Setting up JSDoc and ESLint integration
• Reviewing code documentation quality
• Updating documentation after refactoring

Workflow

1. Identify what to document - Check if element is mandatory (public APIs) or optional
2. Apply appropriate pattern - Use pattern from jsdoc-patterns.md for code element type
3. Include required tags - @param, @returns, @throws, @example for public functions
4. Follow writing style - Present tense, active voice, specific descriptions
5. Validate - Run ESLint to check documentation completeness

Quick Reference

Required for Public Functions

• Brief description
• @param (all parameters with types)
• @returns (for non-void returns)
• @throws (all possible errors)
• @example (for complex functions)

Required for Classes

• @class tag with description
• Constructor documentation
• Public method documentation

Required for Modules

• @fileoverview
• @module tag
• Export documentation

Best Practices

1. Document as you code - Don't defer documentation
2. Be specific - Avoid vague descriptions
3. Document all errors - Use @throws for all exceptions
4. Provide examples - Show realistic usage
5. Keep synchronized - Update docs when code changes
6. Validate with ESLint - Run linting before commit

Common Mistakes

• Missing @param, @returns, or @throws
• Vague descriptions ("processes data")
• Parameter names not matching function signature
• No examples for complex functions
• Outdated documentation after refactoring

Integration

Works with:

• cui-javascript skill - Core JavaScript development
• cui-javascript-unit-testing skill - Test documentation
• ESLint for automated validation
• JSDoc CLI for documentation generation