Add JSDoc linting to kolibri-format and address remediations#14647
Open
rtibbles wants to merge 11 commits intolearningequality:developfrom
Open
Add JSDoc linting to kolibri-format and address remediations#14647rtibbles wants to merge 11 commits intolearningequality:developfrom
rtibbles wants to merge 11 commits intolearningequality:developfrom
Conversation
github-actions
Bot
added
DEV: renderers
Contributor
npm Package VersionsMerging this PR will publish the following packages to npm:
Warning The following packages have changed files but no version bump:
If these changes affect published code, consider bumping the version. |
Contributor
Build Artifacts
Smoke test screenshot |
rtibbles
force-pushed
the
issue-14636-010f06
branch
2 times, most recently
from
56b5c4d to
ce530d2
Compare
Registers eslint-plugin-jsdoc with flat/recommended-error as the base, plus opt-in rules targeting .js and .vue files. Adds `affects` to definedTags so the existing `@affects` convention used in Kolibri composables for documenting outer-state side-effects keeps validating. Version bumped to 2.4.0 (skipping 2.3.0 to avoid collision with the upstream import-x PR). Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Restores typedef references, structured @returns shapes, and inline @type annotations that the upstream JSDoc rules required satisfying; adds typedef imports for previously-undefined types; fills missing @param descriptions, @throws, and @returns declarations. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Restores typedef references and inline @type annotations that the new JSDoc rules required satisfying; adds typedef imports for previously- undefined types (Vue refs, ContentNode, FetchObject, etc.); fills missing @param descriptions, @throws, and @returns declarations. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Adds typedef imports for ESLint and vue-eslint-parser AST types (RuleContext, VElement, Token, ASTNode, Program, etc.) so the rule implementations validate; restores @Private tags and inline @type annotations; fills missing block descriptions and @returns/@throws. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Covers kolibri-build, kolibri-zip, kolibri-sandbox, kolibri-tools, kolibri-module, kolibri-i18n. Restores Language/ContentNode/Theme typedefs in the sandbox embedding shim, typedef imports for opaque types, and fills missing block descriptions, @param descriptions, @throws, and @returns declarations. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Restores typedefs (Quiz/QuizSection/QuizQuestion/QuizExercise), typed @Property entries on UseResourceSelectionResponse and other local types, inline @type annotations on composable refs, and the @affects side-effect documentation on quiz/resource composables. Fills missing block descriptions, @param descriptions, @throws, and @returns declarations. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Adds typedef imports for Vue Ref/ComputedRef and ContentNode-family types used in composables and progress-tracking; restores typed @returns shapes on useCoreLearn; fills missing block descriptions, @param descriptions, @throws, and @returns declarations across the learn-app composables and views. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Restores the HACK note in availableChannelsActions explaining the unlisted-channel workaround; restores Node/SelectedNodes/AnnotatedNode typedefs in treeViewUtils; restores the downloadChannelMetadata JSDoc and the "does not interact with Vuex store" caveat in wizard utils. Fills missing block descriptions, @param descriptions, @throws, and @returns declarations. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Adds typedef import for video.js Component; restores typed @param annotations across the videojs Vue mixins; fills missing block descriptions, @param descriptions, and @returns declarations on the captions/languages/transcript helper modules. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Restores the importLodUsers TODO comment and merged punctuation in wizardMachine; restores the UseActionWithUndoObject typedef and the unmounted-component warning paragraph on useActionWithUndo; restores the "Needed: id, facility, role" caller hint in userManagement actions. Fills missing block descriptions, @param descriptions, @throws, and @returns declarations. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Covers epub_viewer, qti_viewer, and user_auth. Strips a stray period on a URL in qti and fills the few missing JSDoc descriptions and @param descriptions to satisfy the new rules. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
rtibbles
force-pushed
the
issue-14636-010f06
branch
from
ce530d2 to
fa9dbc7
Compare
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
no-blank-blocksno-blank-block-descriptionsinformative-docssort-tagsrequire-descriptionrequire-hyphen-before-param-descriptionrequire-throws@affectsas a tag - because it was pre-existing in some of our JSDoc commentsrequire-jsdocreject-function-typeReferences
Fixes #14636
Reviewer guidance
Are the JSDoc linting rules the right ones?
Take a look at one of the remediation commits to see the changes being made, are they worthwhile?
AI usage
This work was initially done by Claude Code via rtibblesbot, then taken over by me to pare back and remediate its over exuberance.