❌ This issue is not open for contribution. Visit Contributing guidelines to learn about the contributing process and how to find suitable issues.
Overview
Enable eslint-plugin-jsdoc in packages/kolibri-format/eslint.config.mjs to lint JSDoc comments across .js and .vue files, and remediate the pre-existing violations. Uses the flat/recommended-error preset as the base, plus a curated set of opt-in rules covering blank-block hygiene, description quality, tag ordering, and @throws coverage. Includes a minor version bump of kolibri-format.
Complexity: High
Target branch: develop
Context
Kolibri has ~3,100 JSDoc blocks across ~286 frontend files but no JSDoc-specific linting today. As a result, quality varies: blocks with empty descriptions, descriptions that only repeat the symbol name, inconsistent tag ordering, and missing @throws are all present.
kolibri-format (the shared ESLint config at packages/kolibri-format/eslint.config.mjs) is the correct place to add the plugin so both the Kolibri repo and external consumers get the rules. The rules should apply to both .js and .vue files.
The Change
Add eslint-plugin-jsdoc as a dev dependency of kolibri-format and register it in packages/kolibri-format/eslint.config.mjs:
- Extend
jsdoc.configs['flat/recommended-error'] as the base.
- Enable the following opt-in rules as errors:
jsdoc/no-blank-blocksjsdoc/no-blank-block-descriptionsjsdoc/informative-docsjsdoc/sort-tagsjsdoc/require-descriptionjsdoc/require-description-complete-sentencejsdoc/require-hyphen-before-param-descriptionjsdoc/require-throws
Apply the rules to both .js and .vue files.
Remediate the resulting violations across the Kolibri codebase. Where a JSDoc block is trivially wrong (empty, name-echoing), prefer deleting it over padding it to satisfy the rule.
Bump kolibri-format to a new minor version.
How to Get There
After wiring the plugin and rules, run:
pnpm run lint-frontend:format
Many eslint-plugin-jsdoc rules have autofixers (sort-tags, hyphen-before-param-description, description-complete-sentence in some cases). Remaining violations need manual editing or JSDoc block deletion.
Out of Scope
jsdoc/require-jsdoc — does not mandate JSDoc on every function/class; that's a separate, much larger effort.- Other JSDoc rules not listed above (
require-example, require-file-overview, check-examples, TypeScript-flavor rules).
- Authoring new JSDoc for code that currently has none. Remediation fixes or removes existing blocks only.
Acceptance Criteria
References
AI usage
Used Claude Code to draft this issue iteratively. I provided direction on scope and reviewed each section before it was committed. Claude scanned the codebase to gauge existing JSDoc volume (~3,100 blocks across ~286 files) and grouped the plugin's opt-in rules by remediation cost so I could pick a curated set.
❌ This issue is not open for contribution. Visit Contributing guidelines to learn about the contributing process and how to find suitable issues.
Overview
Enable
eslint-plugin-jsdocinpackages/kolibri-format/eslint.config.mjsto lint JSDoc comments across.jsand.vuefiles, and remediate the pre-existing violations. Uses theflat/recommended-errorpreset as the base, plus a curated set of opt-in rules covering blank-block hygiene, description quality, tag ordering, and@throwscoverage. Includes a minor version bump ofkolibri-format.Complexity: High
Target branch: develop
Context
Kolibri has ~3,100 JSDoc blocks across ~286 frontend files but no JSDoc-specific linting today. As a result, quality varies: blocks with empty descriptions, descriptions that only repeat the symbol name, inconsistent tag ordering, and missing
@throwsare all present.kolibri-format(the shared ESLint config atpackages/kolibri-format/eslint.config.mjs) is the correct place to add the plugin so both the Kolibri repo and external consumers get the rules. The rules should apply to both.jsand.vuefiles.The Change
Add
eslint-plugin-jsdocas a dev dependency ofkolibri-formatand register it inpackages/kolibri-format/eslint.config.mjs:jsdoc.configs['flat/recommended-error']as the base.jsdoc/no-blank-blocksjsdoc/no-blank-block-descriptionsjsdoc/informative-docsjsdoc/sort-tagsjsdoc/require-descriptionjsdoc/require-description-complete-sentencejsdoc/require-hyphen-before-param-descriptionjsdoc/require-throwsApply the rules to both
.jsand.vuefiles.Remediate the resulting violations across the Kolibri codebase. Where a JSDoc block is trivially wrong (empty, name-echoing), prefer deleting it over padding it to satisfy the rule.
Bump
kolibri-formatto a new minor version.How to Get There
After wiring the plugin and rules, run:
Many
eslint-plugin-jsdocrules have autofixers (sort-tags, hyphen-before-param-description, description-complete-sentence in some cases). Remaining violations need manual editing or JSDoc block deletion.Out of Scope
jsdoc/require-jsdoc— does not mandate JSDoc on every function/class; that's a separate, much larger effort.require-example,require-file-overview,check-examples, TypeScript-flavor rules).Acceptance Criteria
eslint-plugin-jsdocis added as a dependency ofkolibri-formatjsdoc.configs['flat/recommended-error']is registered as the base preset inpackages/kolibri-format/eslint.config.mjsno-blank-blocks,no-blank-block-descriptions,informative-docs,sort-tags,require-description,require-description-complete-sentence,require-hyphen-before-param-description,require-throws.jsand.vuefilespnpm run lint-frontendpasses with no new violations across the repokolibri-formathas a minor version bump in itspackage.jsonpnpm-lock.yamlis updated for the version bumpReferences
eslint-plugin-jsdocAI usage
Used Claude Code to draft this issue iteratively. I provided direction on scope and reviewed each section before it was committed. Claude scanned the codebase to gauge existing JSDoc volume (~3,100 blocks across ~286 files) and grouped the plugin's opt-in rules by remediation cost so I could pick a curated set.