Use JSDoc to clear types - #989
Open
wherewhere wants to merge 7 commits into
Open
Conversation
Contributor
Author
|
I see group and layout is string, buthexo-theme-next/scripts/tags/group-pictures.js Lines 83 to 84 in 4b24998 templates.dispatch needs number. Is that correct?
|
Contributor
Author
|
Some of the type define maybe ugly... |
There was a problem hiding this comment.
Pull request overview
This PR addresses issue #954 by improving JavaScript type clarity across the NexT theme via JSDoc annotations, TS declaration files, and triple-slash reference directives so editors/type-checkers can infer types instead of falling back to any.
Changes:
- Added extensive JSDoc annotations to
source/jsandscripts/code to improve inferred types. - Introduced
source/js/config.d.tsandsource/js/pjax.d.ts, and wired them via/// <reference ... />. - Updated devDependencies to support the new typing approach (e.g.,
@next-theme/pjax,@types/*).
Reviewed changes
Copilot reviewed 58 out of 60 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| source/js/utils.js | Adds JSDoc types for utilities |
| source/js/third-party/tags/wavedrom.js | Adds utils reference for typing |
| source/js/third-party/tags/pdf.js | Adds utils reference for typing |
| source/js/third-party/tags/mermaid.js | Adds utils reference for typing |
| source/js/third-party/statistics/lean-analytics.js | Adds config reference + JSDoc |
| source/js/third-party/statistics/firestore.js | Adds JSDoc for helpers |
| source/js/third-party/search/local-search.js | Adds search-result typedefs |
| source/js/third-party/search/algolia-search.js | Adds config typing annotations |
| source/js/third-party/quicklink.js | Adds config reference + types |
| source/js/third-party/math/mathjax.js | Adds utils reference for typing |
| source/js/third-party/math/katex.js | Adds utils reference for typing |
| source/js/third-party/comments/utterances.js | Adds utils reference for typing |
| source/js/third-party/comments/livere.js | Adds utils reference for typing |
| source/js/third-party/comments/isso.js | Adds utils reference for typing |
| source/js/third-party/comments/gitalk.js | Adds utils reference for typing |
| source/js/third-party/comments/disqusjs.js | Adds utils reference for typing |
| source/js/third-party/comments/disqus.js | Adds utils reference for typing |
| source/js/third-party/comments/changyan.js | Adds config typing annotations |
| source/js/third-party/chat/chatra.js | Adds config reference for typing |
| source/js/third-party/analytics/matomo.js | Adds config reference for typing |
| source/js/third-party/analytics/growingio.js | Adds deprecation tag + config ref |
| source/js/third-party/analytics/google-analytics.js | Adds config reference for typing |
| source/js/third-party/addtoany.js | Adds utils reference for typing |
| source/js/sidebar.js | Adds config reference for typing |
| source/js/schedule.js | Adds calendar typing annotations |
| source/js/pjax.js | Adds references for pjax types |
| source/js/pjax.d.ts | Declares global Pjax typings |
| source/js/next-boot.js | Adds motion reference for typing |
| source/js/motion.js | Adds motion sequence typedefs |
| source/js/config.js | Adds references + typed helpers |
| source/js/config.d.ts | Declares global CONFIG shape |
| source/js/comments.js | Adds config reference for typing |
| source/js/comments-buttons.js | Adds config reference for typing |
| source/js/bookmark.js | Adds utils reference + JSDoc |
| scripts/tags/wavedrom.js | Adds JSDoc param typing |
| scripts/tags/video.js | Adds JSDoc param typing |
| scripts/tags/tabs.js | Adds ctx/args/content typings |
| scripts/tags/pdf.js | Adds ctx/args typings |
| scripts/tags/note.js | Adds args/content typings |
| scripts/tags/mermaid.js | Adds args/content typings |
| scripts/tags/link-grid.js | Adds content typing |
| scripts/tags/label.js | Adds ctx/args typing |
| scripts/tags/group-pictures.js | Adds JSDoc for helpers/types |
| scripts/tags/center-quote.js | Adds content typing |
| scripts/tags/caniuse.js | Adds ctx/args typing |
| scripts/tags/button.js | Adds ctx/args typing |
| scripts/helpers/next-vendors.js | Adds vendors array typing |
| scripts/helpers/next-url.js | Adds JSDoc typing block |
| scripts/helpers/navigation.js | Adds TreeNode typing for menu helper |
| scripts/helpers/font.js | Adds font config typings |
| scripts/helpers/engine.js | Adds helper parameter typings |
| scripts/filters/minify.js | Removes emitted .d.ts when minifying |
| scripts/filters/comment/common.js | Adds typing for helper funcs |
| scripts/events/lib/vendors.js | Adds hexo param typing |
| scripts/events/lib/utils.js | Adds typings for css parsing helpers |
| scripts/events/lib/navigation.js | Adds typing for menu tree builder |
| scripts/events/lib/injects.js | Adds typing for inject managers |
| scripts/events/lib/highlight.js | Adds typing for theme resolution |
| scripts/events/lib/config.js | Adds hexo param typing |
| package.json | Adds typing-related dev deps |
Suppressed comments (1)
source/js/third-party/search/local-search.js:33
- This annotation still references the misspelled
ReasultItemtypedef. Update it toResultItem[]after renaming the typedef.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+4
to
+11
| /** | ||
| * @typedef {{ | ||
| * item: string, | ||
| * id: number, | ||
| * hitCount: number, | ||
| * includedCount: number | ||
| * }} ReasultItem | ||
| */ |
Comment on lines
+14
to
17
| /** | ||
| * @param {string} name | ||
| */ | ||
| function resolve(name, file = '') { |
Comment on lines
+8
to
+13
| /** | ||
| * @param {string} path | ||
| * @param {string} text | ||
| * @param {Record<string, string>} options | ||
| */ | ||
| = function(path, text, options = {}, decode = false) { |
Comment on lines
22
to
24
| /** @type {HTMLScriptElement} */ | ||
| const targetEle = document.querySelector(`.${className}[data-name="${name}"]`); | ||
| if (!targetEle) return; |
Comment on lines
7
to
8
| /** @type {typeof CONFIG.calendar} */ | ||
| const calendar = { |
Comment on lines
+5
to
+8
| /** | ||
| * @typedef {import('../events/lib/navigation.js').TreeNode} TreeNode | ||
| */ | ||
|
|
| const fs = require('fs'); | ||
| const path = require('path'); | ||
|
|
||
| /** @type {typeof import('@types/css')} */ |
Coverage Report for CI Build 31036603352Coverage increased (+0.7%) to 88.708%Details
Uncovered ChangesNo uncovered changes found. Coverage RegressionsNo coverage regressions found. Coverage Stats
💛 - Coveralls |
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
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.
PR Checklist
PR Type
Issue resolved: #954
Todo List