Merge pull request #5239 from colinrotherham/jsdoc-import

Consider JSDoc `@import` for non-exported types
alphagov · Feb 3, 2025 · f896a78 · f896a78
2 parents 718c40e + 4dd9229
commit f896a78
Show file tree

Hide file tree

Showing 31 changed files with 230 additions and 125 deletions.
diff --git a/.github/workflows/scripts/comments.mjs b/.github/workflows/scripts/comments.mjs
@@ -333,7 +333,8 @@ function getReviewAppUrl(prNumber, path = '/') {
  */
 
 /**
- * @typedef {import('@octokit/plugin-rest-endpoint-methods').RestEndpointMethodTypes["issues"]} IssuesEndpoint
+ * @import {RestEndpointMethodTypes} from '@octokit/plugin-rest-endpoint-methods'
+ * @typedef {RestEndpointMethodTypes["issues"]} IssuesEndpoint
  * @typedef {IssuesEndpoint["listComments"]["parameters"]} IssueCommentsListParams
  * @typedef {IssuesEndpoint["getComment"]["response"]["data"]} IssueCommentData
  */
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -70,7 +70,7 @@
     "eslint-plugin-import": "^2.29.1",
     "eslint-plugin-jest": "^27.9.0",
     "eslint-plugin-jest-dom": "^5.4.0",
-    "eslint-plugin-jsdoc": "^48.2.2",
+    "eslint-plugin-jsdoc": "^50.6.3",
     "eslint-plugin-markdown": "^4.0.1",
     "eslint-plugin-n": "^16.6.2",
     "eslint-plugin-promise": "^6.1.1",

diff --git a/packages/govuk-frontend-review/src/common/nunjucks/globals/get-html-code.mjs b/packages/govuk-frontend-review/src/common/nunjucks/globals/get-html-code.mjs
@@ -13,5 +13,5 @@ export function getHTMLCode(componentName, options) {
 }
 
 /**
- * @typedef {import('@govuk-frontend/lib/components').MacroRenderOptions} MacroRenderOptions
+ * @import {MacroRenderOptions} from '@govuk-frontend/lib/components'
  */
diff --git a/packages/govuk-frontend-review/src/common/nunjucks/globals/get-nunjucks-code.mjs b/packages/govuk-frontend-review/src/common/nunjucks/globals/get-nunjucks-code.mjs
@@ -32,5 +32,5 @@ export function getNunjucksCode(componentName, options) {
 }
 
 /**
- * @typedef {import('@govuk-frontend/lib/components').MacroRenderOptions} MacroRenderOptions
+ * @import {MacroRenderOptions} from '@govuk-frontend/lib/components'
  */
diff --git a/packages/govuk-frontend/babel.config.js b/packages/govuk-frontend/babel.config.js
@@ -27,9 +27,12 @@ module.exports = function (api) {
         )
 
         // Flag any JSDoc comments worth keeping
-        const isDocumentation = ['* @param', '* @returns', '* @typedef'].some(
-          (tag) => comment.includes(tag)
-        )
+        const isDocumentation = [
+          '* @param',
+          '* @returns',
+          '* @typedef',
+          '* @import'
+        ].some((tag) => comment.includes(tag))
 
         // Print only public JSDoc comments
         return !isPrivate && isDocumentation

diff --git a/packages/govuk-frontend/src/govuk-prototype-kit/govuk-prototype-kit.config.unit.test.mjs b/packages/govuk-frontend/src/govuk-prototype-kit/govuk-prototype-kit.config.unit.test.mjs
@@ -3,7 +3,7 @@ import { pkg } from '@govuk-frontend/config'
 import configFn from './govuk-prototype-kit.config.mjs'
 
 describe('GOV.UK Prototype Kit config', () => {
-  /** @type {import('./govuk-prototype-kit.config.mjs').PrototypeKitConfig} */
+  /** @type {PrototypeKitConfig} */
   let config
 
   beforeAll(async () => {
@@ -196,3 +196,7 @@ describe('GOV.UK Prototype Kit config', () => {
     })
   })
 })
+
+/**
+ * @import { PrototypeKitConfig } from './govuk-prototype-kit.config.mjs'
+ */
diff --git a/packages/govuk-frontend/src/govuk/all.mjs b/packages/govuk-frontend/src/govuk/all.mjs
@@ -18,6 +18,6 @@ export { GOVUKFrontendComponent as Component } from './govuk-frontend-component.
 export { ConfigurableComponent } from './common/configuration.mjs'
 
 /**
- * @typedef {import('./init.mjs').Config} Config
- * @typedef {import('./init.mjs').ConfigKey} ConfigKey
+ * @typedef {import('./init.mjs').Config} Config for all components via `initAll()`
+ * @typedef {import('./init.mjs').ConfigKey} ConfigKey - Component config keys, e.g. `accordion` and `characterCount`
  */
diff --git a/.../govuk-frontend/src/govuk/common/configuration/extract-config-by-namespace.jsdom.test.mjs b/.../govuk-frontend/src/govuk/common/configuration/extract-config-by-namespace.jsdom.test.mjs
@@ -261,5 +261,5 @@ describe('extractConfigByNamespace', () => {
 })
 
 /**
- * @typedef {import('../configuration.mjs').Schema} Schema
+ * @import { Schema } from '../configuration.mjs'
  */
diff --git a/packages/govuk-frontend/src/govuk/common/configuration/normalise-dataset.jsdom.test.mjs b/packages/govuk-frontend/src/govuk/common/configuration/normalise-dataset.jsdom.test.mjs
@@ -54,5 +54,5 @@ describe('normaliseDataset', () => {
 })
 
 /**
- * @typedef {import('./../configuration.mjs').Schema} Schema
+ * @import { Schema } from './../configuration.mjs'
  */
diff --git a/packages/govuk-frontend/src/govuk/components/accordion/accordion.mjs b/packages/govuk-frontend/src/govuk/components/accordion/accordion.mjs
@@ -639,5 +639,5 @@ export class Accordion extends ConfigurableComponent {
  */
 
 /**
- * @typedef {import('../../common/configuration.mjs').Schema} Schema
+ * @import { Schema } from '../../common/configuration.mjs'
  */
diff --git a/packages/govuk-frontend/src/govuk/components/button/button.mjs b/packages/govuk-frontend/src/govuk/components/button/button.mjs
@@ -122,5 +122,5 @@ export class Button extends ConfigurableComponent {
  */
 
 /**
- * @typedef {import('../../common/configuration.mjs').Schema} Schema
+ * @import { Schema } from '../../common/configuration.mjs'
  */
-Original file line number
+Diff line change
@@ Expand Up / @@ -13,5 +13,5 @@ export function getHTMLCode(componentName, options) { @@
     }
     /**
-     * @typedef {import('@govuk-frontend/lib/components').MacroRenderOptions} MacroRenderOptions
+     * @import {MacroRenderOptions} from '@govuk-frontend/lib/components'
      */