Jsdoc Best Practices

What it does

This skill enforces JSDoc best practices within a JavaScript project, ensuring code is well-documented for maintainability and developer understanding. It emphasizes documenting why code exists and how it functions, rather than simply restating what the code already does. The skill utilizes eslint-plugin-jsdoc to automatically check and enforce these standards.

When to use it

• When onboarding new developers to a JavaScript project with existing JSDoc conventions.
• During code reviews to ensure documentation aligns with established best practices.
• To improve the overall clarity and maintainability of a JavaScript codebase.
• When integrating with tools like DataLoader that require specific documentation patterns.

Key capabilities

• Enforces JSDoc on function declarations, interfaces, type aliases, and PascalCase arrow functions.
• Requires descriptions for @param, @returns, and @property tags.
• Allows the use of the @remarks tag to document context, constraints, and non-obvious behavior ("why").
• Uses eslint-plugin-jsdoc for automated rule enforcement.

Example prompts

Since this is an ESLint integration skill, there are no direct user prompts. Instead, it works automatically within a development environment. A developer might see errors or warnings from their IDE indicating JSDoc violations that need to be addressed.

Tips & gotchas

• This skill requires eslint-plugin-jsdoc to be installed and configured in your project's ESLint setup.
• The focus is on documenting "why" – provide context and reasoning, not just a restatement of the code’s functionality.
• Be aware that the skill enforces specific JSDoc tag requirements (e.g., descriptions for @param and @returns).