Update jsdoc to 4 and use jsdoc-wmf-theme

Change-Id: Idb33efa5b714826550917397d4de1f2e5087f1bd
This commit is contained in:
Ed Sanders 2023-11-17 16:13:03 +00:00 committed by James D. Forrester
parent 253399c3d1
commit 9b8b402cb1
15 changed files with 191 additions and 67 deletions

View file

@ -2,9 +2,10 @@
"opts": {
"destination": "docs/js",
"package": "package.json",
"pedantic": true,
"pedantic": false,
"readme": "README.md",
"recurse": true
"recurse": true,
"template": "node_modules/jsdoc-wmf-theme"
},
"plugins": [
"plugins/markdown"
@ -16,6 +17,26 @@
"cleverLinks": true,
"default": {
"useLongnameInNav": true
},
"wmf": {
"linkMap": {
"Array": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array",
"Event": "https://developer.mozilla.org/en-US/docs/Web/API/Event",
"HTMLElement": "https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement",
"HTMLAnchorElement": "https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement",
"NodeList": "https://developer.mozilla.org/en-US/docs/Web/API/NodeList",
"Promise": "https://developer.mozilla.org/en-US/docs/Web/API/Promise",
"jQuery": "https://api.jquery.com/Types/#jQuery",
"jQuery.Promise": "https://api.jquery.com/Types/#Promise",
"jQuery.jqXHR": "https://api.jquery.com/Types/#jqXHR",
"Redux.Store": "https://redux.js.org/api/store",
"Redux.Thunk": "https://redux.js.org/usage/writing-logic-thunks",
"mw.Api": "https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api",
"mw.Map": "https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Map",
"mw.SafeStorage": "https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.SafeStorage",
"mw.Title": "https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title",
"mw.User": "https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.User"
}
}
}
}

183
package-lock.json generated
View file

@ -30,7 +30,8 @@
"expose-loader": "4.1.0",
"grunt-banana-checker": "0.11.1",
"jquery": "3.7.1",
"jsdoc": "3.6.10",
"jsdoc": "4.0.2",
"jsdoc-wmf-theme": "1.0.0",
"less": "3.13.1",
"less-loader": "11.1.4",
"nyc": "15.0.0",
@ -1752,6 +1753,18 @@
"@jridgewell/sourcemap-codec": "^1.4.14"
}
},
"node_modules/@jsdoc/salty": {
"version": "0.2.8",
"resolved": "https://registry.npmjs.org/@jsdoc/salty/-/salty-0.2.8.tgz",
"integrity": "sha512-5e+SFVavj1ORKlKaKr2BmTOekmXbelU7dC0cDkQLqag7xfuTPuGMUFx7KWJuv4bYZrTsoL2Z18VVCOKYxzoHcg==",
"dev": true,
"dependencies": {
"lodash": "^4.17.21"
},
"engines": {
"node": ">=v12.0.0"
}
},
"node_modules/@mdn/browser-compat-data": {
"version": "5.3.29",
"resolved": "https://registry.npmjs.org/@mdn/browser-compat-data/-/browser-compat-data-5.3.29.tgz",
@ -3371,6 +3384,16 @@
"vue": "^3.2.37"
}
},
"node_modules/@wikimedia/codex-design-tokens": {
"version": "1.1.1",
"resolved": "https://registry.npmjs.org/@wikimedia/codex-design-tokens/-/codex-design-tokens-1.1.1.tgz",
"integrity": "sha512-qFX7LcR/l90yqVTBApvrIDY3Xa0WifoMlBJRGD1DoWff8e/yMhLmxF1o2DRcIfQlOvKDg0Vhy8jAttF6MUfMAA==",
"dev": true,
"engines": {
"node": ">=16",
"npm": ">=7.21.0"
}
},
"node_modules/@wikimedia/codex-icons": {
"version": "0.14.0",
"resolved": "https://registry.npmjs.org/@wikimedia/codex-icons/-/codex-icons-0.14.0.tgz",
@ -6062,6 +6085,12 @@
"node": ">=12"
}
},
"node_modules/domino": {
"version": "2.1.6",
"resolved": "https://registry.npmjs.org/domino/-/domino-2.1.6.tgz",
"integrity": "sha512-3VdM/SXBZX2omc9JF9nOPCtDaYQ67BGp5CoLpIQlO2KCAPETs8TcDHacF26jXadGbvUteZzRTeos2fhID5+ucQ==",
"dev": true
},
"node_modules/duplexer": {
"version": "0.1.2",
"resolved": "https://registry.npmjs.org/duplexer/-/duplexer-0.1.2.tgz",
@ -9417,32 +9446,32 @@
"dev": true
},
"node_modules/jsdoc": {
"version": "3.6.10",
"resolved": "https://registry.npmjs.org/jsdoc/-/jsdoc-3.6.10.tgz",
"integrity": "sha512-IdQ8ppSo5LKZ9o3M+LKIIK8i00DIe5msDvG3G81Km+1dhy0XrOWD0Ji8H61ElgyEj/O9KRLokgKbAM9XX9CJAg==",
"version": "4.0.2",
"resolved": "https://registry.npmjs.org/jsdoc/-/jsdoc-4.0.2.tgz",
"integrity": "sha512-e8cIg2z62InH7azBBi3EsSEqrKx+nUtAS5bBcYTSpZFA+vhNPyhv8PTFZ0WsjOPDj04/dOLlm08EDcQJDqaGQg==",
"dev": true,
"dependencies": {
"@babel/parser": "^7.9.4",
"@babel/parser": "^7.20.15",
"@jsdoc/salty": "^0.2.1",
"@types/markdown-it": "^12.2.3",
"bluebird": "^3.7.2",
"catharsis": "^0.9.0",
"escape-string-regexp": "^2.0.0",
"js2xmlparser": "^4.0.2",
"klaw": "^4.0.1",
"klaw": "^3.0.0",
"markdown-it": "^12.3.2",
"markdown-it-anchor": "^8.4.1",
"marked": "^4.0.10",
"mkdirp": "^1.0.4",
"requizzle": "^0.2.3",
"strip-json-comments": "^3.1.0",
"taffydb": "2.6.2",
"underscore": "~1.13.2"
},
"bin": {
"jsdoc": "jsdoc.js"
},
"engines": {
"node": ">=8.15.0"
"node": ">=12.0.0"
}
},
"node_modules/jsdoc-type-pratt-parser": {
@ -9454,6 +9483,32 @@
"node": ">=12.0.0"
}
},
"node_modules/jsdoc-wmf-theme": {
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/jsdoc-wmf-theme/-/jsdoc-wmf-theme-1.0.0.tgz",
"integrity": "sha512-DAR0Rna+X5/Hzlmt297Y05BLPGdUfBUBXfdMwiSJjh8cpLZxt9lHjw2SYnzOpPAPuJYWW3t6MkoJMG0i9cv+uQ==",
"dev": true,
"dependencies": {
"@jsdoc/salty": "^0.2.7",
"@wikimedia/codex-design-tokens": "1.1.1",
"domino": "^2.1.6",
"lunr": "2.3.9",
"marked": "^12.0.1",
"normalize.css": "8.0.1"
}
},
"node_modules/jsdoc-wmf-theme/node_modules/marked": {
"version": "12.0.2",
"resolved": "https://registry.npmjs.org/marked/-/marked-12.0.2.tgz",
"integrity": "sha512-qXUm7e/YKFoqFPYPa3Ukg9xlI5cyAtGmyEIzMfW//m6kXwCy2Ps9DYf5ioijFKQ8qyuscrHoY04iJGctu2Kg0Q==",
"dev": true,
"bin": {
"marked": "bin/marked.js"
},
"engines": {
"node": ">= 18"
}
},
"node_modules/jsdoc/node_modules/escape-string-regexp": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-2.0.0.tgz",
@ -9675,12 +9730,12 @@
}
},
"node_modules/klaw": {
"version": "4.0.1",
"resolved": "https://registry.npmjs.org/klaw/-/klaw-4.0.1.tgz",
"integrity": "sha512-pgsE40/SvC7st04AHiISNewaIMUbY5V/K8b21ekiPiFoYs/EYSdsGa+FJArB1d441uq4Q8zZyIxvAzkGNlBdRw==",
"version": "3.0.0",
"resolved": "https://registry.npmjs.org/klaw/-/klaw-3.0.0.tgz",
"integrity": "sha512-0Fo5oir+O9jnXu5EefYbVK+mHMBeEVEy2cmctR1O1NECcCkPRreJKrS6Qt/j3KC2C148Dfo9i3pCmCMsdqGr0g==",
"dev": true,
"engines": {
"node": ">=14.14.0"
"dependencies": {
"graceful-fs": "^4.1.9"
}
},
"node_modules/known-css-properties": {
@ -10197,6 +10252,12 @@
"node": ">=10"
}
},
"node_modules/lunr": {
"version": "2.3.9",
"resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz",
"integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==",
"dev": true
},
"node_modules/magic-string": {
"version": "0.30.0",
"resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.0.tgz",
@ -10996,6 +11057,12 @@
"url": "https://github.com/sponsors/sindresorhus"
}
},
"node_modules/normalize.css": {
"version": "8.0.1",
"resolved": "https://registry.npmjs.org/normalize.css/-/normalize.css-8.0.1.tgz",
"integrity": "sha512-qizSNPO93t1YUuUhP22btGOo3chcvDFqFaj2TRybP0DMxkHOCTYwp3n34fel4a31ORXy4m1Xq0Gyqpb5m33qIg==",
"dev": true
},
"node_modules/npmlog": {
"version": "4.1.2",
"resolved": "https://registry.npmjs.org/npmlog/-/npmlog-4.1.2.tgz",
@ -14121,12 +14188,6 @@
"integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
"dev": true
},
"node_modules/taffydb": {
"version": "2.6.2",
"resolved": "https://registry.npmjs.org/taffydb/-/taffydb-2.6.2.tgz",
"integrity": "sha512-y3JaeRSplks6NYQuCOj3ZFMO3j60rTwbuKCvZxsAraGYH2epusatvZ0baZYA01WsGqJBq/Dl6vOrMUJqyMj8kA==",
"dev": true
},
"node_modules/tap-mocha-reporter": {
"version": "5.0.1",
"resolved": "https://registry.npmjs.org/tap-mocha-reporter/-/tap-mocha-reporter-5.0.1.tgz",
@ -16936,6 +16997,15 @@
"@jridgewell/sourcemap-codec": "^1.4.14"
}
},
"@jsdoc/salty": {
"version": "0.2.8",
"resolved": "https://registry.npmjs.org/@jsdoc/salty/-/salty-0.2.8.tgz",
"integrity": "sha512-5e+SFVavj1ORKlKaKr2BmTOekmXbelU7dC0cDkQLqag7xfuTPuGMUFx7KWJuv4bYZrTsoL2Z18VVCOKYxzoHcg==",
"dev": true,
"requires": {
"lodash": "^4.17.21"
}
},
"@mdn/browser-compat-data": {
"version": "5.3.29",
"resolved": "https://registry.npmjs.org/@mdn/browser-compat-data/-/browser-compat-data-5.3.29.tgz",
@ -18301,6 +18371,12 @@
"dev": true,
"requires": {}
},
"@wikimedia/codex-design-tokens": {
"version": "1.1.1",
"resolved": "https://registry.npmjs.org/@wikimedia/codex-design-tokens/-/codex-design-tokens-1.1.1.tgz",
"integrity": "sha512-qFX7LcR/l90yqVTBApvrIDY3Xa0WifoMlBJRGD1DoWff8e/yMhLmxF1o2DRcIfQlOvKDg0Vhy8jAttF6MUfMAA==",
"dev": true
},
"@wikimedia/codex-icons": {
"version": "0.14.0",
"resolved": "https://registry.npmjs.org/@wikimedia/codex-icons/-/codex-icons-0.14.0.tgz",
@ -20362,6 +20438,12 @@
"webidl-conversions": "^7.0.0"
}
},
"domino": {
"version": "2.1.6",
"resolved": "https://registry.npmjs.org/domino/-/domino-2.1.6.tgz",
"integrity": "sha512-3VdM/SXBZX2omc9JF9nOPCtDaYQ67BGp5CoLpIQlO2KCAPETs8TcDHacF26jXadGbvUteZzRTeos2fhID5+ucQ==",
"dev": true
},
"duplexer": {
"version": "0.1.2",
"resolved": "https://registry.npmjs.org/duplexer/-/duplexer-0.1.2.tgz",
@ -22834,25 +22916,25 @@
"dev": true
},
"jsdoc": {
"version": "3.6.10",
"resolved": "https://registry.npmjs.org/jsdoc/-/jsdoc-3.6.10.tgz",
"integrity": "sha512-IdQ8ppSo5LKZ9o3M+LKIIK8i00DIe5msDvG3G81Km+1dhy0XrOWD0Ji8H61ElgyEj/O9KRLokgKbAM9XX9CJAg==",
"version": "4.0.2",
"resolved": "https://registry.npmjs.org/jsdoc/-/jsdoc-4.0.2.tgz",
"integrity": "sha512-e8cIg2z62InH7azBBi3EsSEqrKx+nUtAS5bBcYTSpZFA+vhNPyhv8PTFZ0WsjOPDj04/dOLlm08EDcQJDqaGQg==",
"dev": true,
"requires": {
"@babel/parser": "^7.9.4",
"@babel/parser": "^7.20.15",
"@jsdoc/salty": "^0.2.1",
"@types/markdown-it": "^12.2.3",
"bluebird": "^3.7.2",
"catharsis": "^0.9.0",
"escape-string-regexp": "^2.0.0",
"js2xmlparser": "^4.0.2",
"klaw": "^4.0.1",
"klaw": "^3.0.0",
"markdown-it": "^12.3.2",
"markdown-it-anchor": "^8.4.1",
"marked": "^4.0.10",
"mkdirp": "^1.0.4",
"requizzle": "^0.2.3",
"strip-json-comments": "^3.1.0",
"taffydb": "2.6.2",
"underscore": "~1.13.2"
},
"dependencies": {
@ -22876,6 +22958,28 @@
"integrity": "sha512-YtOli5Cmzy3q4dP26GraSOeAhqecewG04hoO8DY56CH4KJ9Fvv5qKWUCCo3HZob7esJQHCv6/+bnTy72xZZaVQ==",
"dev": true
},
"jsdoc-wmf-theme": {
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/jsdoc-wmf-theme/-/jsdoc-wmf-theme-1.0.0.tgz",
"integrity": "sha512-DAR0Rna+X5/Hzlmt297Y05BLPGdUfBUBXfdMwiSJjh8cpLZxt9lHjw2SYnzOpPAPuJYWW3t6MkoJMG0i9cv+uQ==",
"dev": true,
"requires": {
"@jsdoc/salty": "^0.2.7",
"@wikimedia/codex-design-tokens": "1.1.1",
"domino": "^2.1.6",
"lunr": "2.3.9",
"marked": "^12.0.1",
"normalize.css": "8.0.1"
},
"dependencies": {
"marked": {
"version": "12.0.2",
"resolved": "https://registry.npmjs.org/marked/-/marked-12.0.2.tgz",
"integrity": "sha512-qXUm7e/YKFoqFPYPa3Ukg9xlI5cyAtGmyEIzMfW//m6kXwCy2Ps9DYf5ioijFKQ8qyuscrHoY04iJGctu2Kg0Q==",
"dev": true
}
}
},
"jsdom": {
"version": "18.0.1",
"resolved": "https://registry.npmjs.org/jsdom/-/jsdom-18.0.1.tgz",
@ -23038,10 +23142,13 @@
"dev": true
},
"klaw": {
"version": "4.0.1",
"resolved": "https://registry.npmjs.org/klaw/-/klaw-4.0.1.tgz",
"integrity": "sha512-pgsE40/SvC7st04AHiISNewaIMUbY5V/K8b21ekiPiFoYs/EYSdsGa+FJArB1d441uq4Q8zZyIxvAzkGNlBdRw==",
"dev": true
"version": "3.0.0",
"resolved": "https://registry.npmjs.org/klaw/-/klaw-3.0.0.tgz",
"integrity": "sha512-0Fo5oir+O9jnXu5EefYbVK+mHMBeEVEy2cmctR1O1NECcCkPRreJKrS6Qt/j3KC2C148Dfo9i3pCmCMsdqGr0g==",
"dev": true,
"requires": {
"graceful-fs": "^4.1.9"
}
},
"known-css-properties": {
"version": "0.27.0",
@ -23466,6 +23573,12 @@
"yallist": "^4.0.0"
}
},
"lunr": {
"version": "2.3.9",
"resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz",
"integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==",
"dev": true
},
"magic-string": {
"version": "0.30.0",
"resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.0.tgz",
@ -24077,6 +24190,12 @@
"integrity": "sha512-DlL+XwOy3NxAQ8xuC0okPgK46iuVNAK01YN7RueYBqqFeGsBjV9XmCAzAdgt+667bCl5kPh9EqKKDwnaPG1I7A==",
"dev": true
},
"normalize.css": {
"version": "8.0.1",
"resolved": "https://registry.npmjs.org/normalize.css/-/normalize.css-8.0.1.tgz",
"integrity": "sha512-qizSNPO93t1YUuUhP22btGOo3chcvDFqFaj2TRybP0DMxkHOCTYwp3n34fel4a31ORXy4m1Xq0Gyqpb5m33qIg==",
"dev": true
},
"npmlog": {
"version": "4.1.2",
"resolved": "https://registry.npmjs.org/npmlog/-/npmlog-4.1.2.tgz",
@ -26474,12 +26593,6 @@
}
}
},
"taffydb": {
"version": "2.6.2",
"resolved": "https://registry.npmjs.org/taffydb/-/taffydb-2.6.2.tgz",
"integrity": "sha512-y3JaeRSplks6NYQuCOj3ZFMO3j60rTwbuKCvZxsAraGYH2epusatvZ0baZYA01WsGqJBq/Dl6vOrMUJqyMj8kA==",
"dev": true
},
"tap-mocha-reporter": {
"version": "5.0.1",
"resolved": "https://registry.npmjs.org/tap-mocha-reporter/-/tap-mocha-reporter-5.0.1.tgz",

View file

@ -14,7 +14,7 @@
"test:lint:i18n": "banana-checker --requireLowerCase=0 i18n/",
"check-built-assets": "echo 'CHECKING BUILD SOURCES ARE COMMITTED OR STAGED' && npm -s run build && git diff --exit-code resources/dist || { npm run node-debug; false; }",
"coverage": "nyc --reporter=lcov npm -s run test:unit",
"doc": "jsdoc -c jsdoc.json # SKIPPED! && npm run build-storybook",
"doc": "jsdoc -c jsdoc.json && cp popups.svg docs/js # SKIPPED! && npm run build-storybook",
"linter:js": "eslint --cache .",
"linter:styles": "stylelint \"src/**/*.less\"",
"minify:svg": "svgo --config=.svgo.config.js --quiet --recursive --folder resources/ext.popups.images/",
@ -51,7 +51,8 @@
"expose-loader": "4.1.0",
"grunt-banana-checker": "0.11.1",
"jquery": "3.7.1",
"jsdoc": "3.6.10",
"jsdoc": "4.0.2",
"jsdoc-wmf-theme": "1.0.0",
"less": "3.13.1",
"less-loader": "11.1.4",
"nyc": "15.0.0",

Binary file not shown.

View file

@ -1,3 +1,7 @@
/**
* @module canSaveToUserPreferences
*/
/**
* Can the current user save to user preferences?
*

View file

@ -13,9 +13,6 @@ export default function createContainer() {
/**
* The interface implemented by all service containers.
*
* @interface Container
* @global
*/
return {
/**

View file

@ -2,12 +2,6 @@
* @module experiments
*/
/**
* @interface Experiments
*
* @global
*/
/**
* Creates a helper wrapper for the MediaWiki-provided
* `mw.experiments#getBucket` bucketing function.

View file

@ -1,3 +1,7 @@
/**
* @module formatter
*/
/**
* Improves the plain text extracts
*

View file

@ -1,3 +1,7 @@
/**
* @module restFormatters
*/
import * as formatter from '../formatter';
/**

View file

@ -57,8 +57,6 @@ const EXCLUDED_LINK_SELECTORS = [
*
* @param {string} topic
* @param {Object} data
*
* @global
*/
/**

View file

@ -1,5 +1,5 @@
/**
* @module MediaWiki-Popups Integration
* @module MediaWiki-Popups-Integration
*/
import { previewTypes } from '../preview/model';

View file

@ -29,8 +29,6 @@ export { previewTypes };
* @typedef {Object} PreviewModel
* @property {string} url The canonical URL of the page being previewed
* @property {string} type One of the previewTypes.TYPE_ constants.
*
* @global
*/
/**
@ -44,8 +42,6 @@ export { previewTypes };
* @property {string} languageDirection Either "ltr" or "rtl", or an empty string if undefined.
* @property {{source: string, width: number, height: number}|undefined} thumbnail
* @property {number} pageId Currently not used by any known popup type.
*
* @global
*/
/**
@ -54,8 +50,6 @@ export { previewTypes };
* @property {string} extract An HTML snippet, not necessarily with a single top-level node
* @property {string} referenceType A type identifier, e.g. "web"
* @property {string} sourceElementId ID of the parent element that triggered the preview
*
* @global
*/
/**

View file

@ -1,3 +1,7 @@
/**
* @module nextState
*/
/**
* Creates the next state tree from the current state tree and some updates.
*

View file

@ -12,8 +12,6 @@ import { escapeHTML } from '../templateUtil';
* @property {string} helpText
* @property {string} okLabel
* @property {SettingsChoiceModel[]} [choices]
*
* @global
*/
/**
@ -22,8 +20,6 @@ import { escapeHTML } from '../templateUtil';
* @property {string} name
* @property {string} [description]
* @property {boolean} [isChecked] Whether the setting is checked.
*
* @global
*/
/**

View file

@ -4,12 +4,6 @@ import { previewTypes } from './preview/model';
* @module userSettings
*/
/**
* @interface UserSettings
*
* @global
*/
const PAGE_PREVIEWS_ENABLED_KEY = 'mwe-popups-enabled',
REFERENCE_PREVIEWS_ENABLED_KEY = 'mwe-popups-referencePreviews-enabled',
PAGE_PREVIEWS_CHANGE_SETTING_EVENT = 'Popups.SettingChange';