majiayu000 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
- Identify what to document - Check if element is mandatory (public APIs) or optional
- Apply appropriate pattern - Use pattern from jsdoc-patterns.md for code element type
- Include required tags - @param, @returns, @throws, @example for public functions
- Follow writing style - Present tense, active voice, specific descriptions
- 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
- Document as you code - Don't defer documentation
- Be specific - Avoid vague descriptions
- Document all errors - Use @throws for all exceptions
- Provide examples - Show realistic usage
- Keep synchronized - Update docs when code changes
- 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