We currently maintain an exclude list of files that should not be included in jsdoc documentation. This was expedited to unblock use of ES6 in MediaWiki core. We hope to complete this porting by the next MediaWiki 1.42 Release, although CI will need to continue supporting JSDuck to generate the documentation for the REL1_39 branch which is supported until November 2025.
https://gerrit.wikimedia.org/g/mediawiki/core/+/29af4dd074ecc71c67bb9e530d82daddcf45c724/jsdoc.js#18
# Migration plan
[x] 1. Switch to JSDoc from JSDuck for [one module](https://doc.wikimedia.org/mediawiki-core/master/js/mw.module_util.html) and provide [link to old version of documentation](https://doc.wikimedia.org/mediawiki-core/master/js/index.html) so that use of ES6 is unblocked.
[x] Review documentation example with technical documentation team.
[x] 2. Port all other files to jsdoc. Porting should be prioritized based on user needs. During this phase we should consider what code should not be ported to the new documentation and pay attention to improving documentation where possible e.g. adding examples.
[x] Go through the following list and decide whether the code needs to included in the documentation or excluded from the documented. We will prioritize porting of public stable APIs used by gadget developers and alter the priorities based on feedback from the [talk page](https://www.mediawiki.org/wiki/Talk:JSDoc_WMF_theme).
[ ] 3. Final review. After everything is ported, review with technical documentation team and identify follow up work. ([Tracking spreadsheet](https://docs.google.com/spreadsheets/d/1hw2GrwvdPONp6pqNxiReGKx-B0FMugXEaVw9WnHbvvM/edit#gid=0))
# TODO
1. Claim an item in the list by adding your name next to it.
2. Make sure you have the latest version of MediaWiki core.
3. Edit [jsdoc.js](https://gerrit.wikimedia.org/g/mediawiki/core/%2B/master/jsdoc.js), and move the file that you're migrating from the `exclude` section to the `include` section.
4. Run `npm run doc` to update the local docs site.
5. Open docs/js/index.html to view the site.
6. Look through the local docs site, and find the elements from the file you're migrating. Does everything not marked as `@private` show up? Is it organized in a way that makes sense? You can check out the same content on the [old JSDuck site for MediaWiki version 1.41](https://doc.wikimedia.org/mediawiki-core/REL1_41/js/) to see if the new site is presenting the same information in roughly the same way. If not, you'll need to adjust the tags to comply with JSDoc. See the chart on T138401 for specific mappings from JSDuck tags to JSDoc tags.
8. Re-run `npm run doc` to preview your changes.
Tips and best practices:
* Only public and stable methods should appear on the docs site.
* Make sure every function has a description in the main section of the doc block.
* Add an `@example` if you think they will be useful.
* For singleton classes, use a `@namespace` tag.
* Follow patterns in existing examples. Document hooks under namespace Hooks and jQuery plugins under jQueryPlugins namespace.
* Fix any related jsdoc warnings.
* You can run `npx grunt eslint` to find JSDoc errors.
* If something isn't appearing on the docs site, you may need to add a `@memberof` tag with the namespace.
In order of priority:
Check the box once the patch is merged.
## Phase 1
[x] resources/src/mediawiki.util (https://gerrit.wikimedia.org/r/c/mediawiki/core/+/975921/)
[X] resources/src/mediawiki.base (https://gerrit.wikimedia.org/r/c/mediawiki/core/+/978717)
[X] resources/src/mediawiki.notification (https://gerrit.wikimedia.org/r/c/mediawiki/core/+/978717)
[X] resources/src/startup (https://gerrit.wikimedia.org/r/c/mediawiki/core/+/978717)
[x] resources/src/mediawiki.Title https://gerrit.wikimedia.org/r/c/mediawiki/core/+/982917
[x] resources/src/mediawiki.user.js (https://gerrit.wikimedia.org/r/c/mediawiki/core/+/983265, https://gerrit.wikimedia.org/r/c/mediawiki/core/+/983973)
[x] resources/src/mediawiki.api (https://gerrit.wikimedia.org/r/c/mediawiki/core/+/982932)
[x] resources/src/mediawiki.Uri (https://gerrit.wikimedia.org/r/c/mediawiki/core/+/982815, https://gerrit.wikimedia.org/r/c/mediawiki/core/+/983973)
[x] resources/src/mediawiki.ForeignUpload.js https://gerrit.wikimedia.org/r/c/mediawiki/core/+/982939
[x] resources/src/mediawiki.String.js [Jon] https://gerrit.wikimedia.org/r/c/mediawiki/core/+/982509
## Phase 2
[x] resources/src/jquery.lengthLimit.js (https://gerrit.wikimedia.org/r/c/mediawiki/core/+/982856)
[x] resources/src/mediawiki.experiments.js (https://gerrit.wikimedia.org/r/c/mediawiki/core/+/982861)
[x] resources/src/mediawiki.Upload.js (https://gerrit.wikimedia.org/r/c/mediawiki/core/+/982939/1)
[x] resources/src/mediawiki.cookie (https://gerrit.wikimedia.org/r/c/mediawiki/core/+/983220)
[x] resources/src/mediawiki.storage.js (https://gerrit.wikimedia.org/r/c/mediawiki/core/+/983263)
[x] resources/src/mediawiki.page.watch.ajax (https://gerrit.wikimedia.org/r/c/mediawiki/core/+/983498)
[x] resources/src/mediawiki.page.ready https://gerrit.wikimedia.org/r/c/mediawiki/core/+/984266
[x] resources/src/mediawiki.template.js https://gerrit.wikimedia.org/r/c/mediawiki/core/+/987490
[x] resources/src/mediawiki.template.mustache.js https://gerrit.wikimedia.org/r/c/mediawiki/core/+/987490
[x] resources/src/mediawiki.feedback https://gerrit.wikimedia.org/r/c/mediawiki/core/+/987825
[x] resources/src/jquery https://gerrit.wikimedia.org/r/c/mediawiki/core/+/987836
[x] resources/src/jquery.spinner https://gerrit.wikimedia.org/r/c/mediawiki/core/+/987836
[x] resources/src/jquery.tablesorter https://gerrit.wikimedia.org/r/c/mediawiki/core/+/987836
[x] resources/src/mediawiki.widgets https://gerrit.wikimedia.org/r/c/mediawiki/core/+/988731
## Phase 3 [https://gerrit.wikimedia.org/r/c/mediawiki/core/+/988733/]
The following modules do not appear to have public APIs. We should include them in jsdoc.json and make sure no changes happen to the documentation. You may need to add @ignore to a few things.
[x] resources/src/mediawiki.page.image.pagination.js
[x] resources/src/mediawiki.page.media.js
[x] resources/src/mediawiki.special.block.js
[x] resources/src/mediawiki.page.gallery.js
[x] resources/src/mediawiki.userSuggest.js
[x] resources/src/mediawiki.special.userrights.js
[x] resources/src/mediawiki.special.search.commonsInterwikiWidget.js
[x] resources/src/mediawiki.special.contributions.js
[x] resources/src/mediawiki.checkboxtoggle.js
[x] resources/src/mediawiki.special.changeslist.legend.js
[x] resources/src/mediawiki.special.changeemail.js
[x] resources/src/mediawiki.special.changecredentails.js
[x] resources/src/mediawiki.misc-authed-pref
[x] resources/src/mediawiki.toc
[x] resources/src/mediawiki.pulsatingdot
[x] resources/src/mediawiki.skinning
[x] resources/src/mediawiki.special
[x] resources/src/mediawiki.action
[x] resources/src/mediawiki.action.edit
[x] resources/src/mediawiki.special.changeslist
[x] resources/src/mediawiki.apipretty
[x] resources/src/mediawiki.special.changeslist.watchlistexpiry
[x] resources/src/mediawiki.special.createaccount
[x] resources/src/mediawiki.special.editrecovery
[x] resources/src/mediawiki.special.search
[x] resources/src/mediawiki.diff
[x] resources/src/mediawiki.special.unwatchedPages
[x] resources/src/mediawiki.editRecovery
[x] resources/src/mediawiki.filewarning
[x] resources/src/mediawiki.special.watchlist
[x] resources/src/mediawiki.helplink
[x] resources/src/mediawiki.htmlform
[x] resources/src/mediawiki.tempUserBanner
[x] resources/src/mediawiki.language.names
[x] resources/src/mediawiki.misc-authed-curate
[x] resources/src/mediawiki.misc-authed-ooui
## Phase 4
[x] resources/src/mediawiki.page.preview.js (https://gerrit.wikimedia.org/r/c/mediawiki/core/+/983511)
[x] resources/src/mediawiki.cldr https://gerrit.wikimedia.org/r/c/mediawiki/core/+/991408
[x] resources/src/mediawiki.feedlink https://gerrit.wikimedia.org/r/c/mediawiki/core/+/991408
[x] resources/src/mediawiki.visibleTimeout https://gerrit.wikimedia.org/r/c/mediawiki/core/+/991408
[x] resources/src/mediawiki.confirmCloseWindow.js https://gerrit.wikimedia.org/r/c/mediawiki/core/+/991408
[x] resources/src/mediawiki.debug https://gerrit.wikimedia.org/r/c/mediawiki/core/+/991408
[x] resources/src/mediawiki.deflate https://gerrit.wikimedia.org/r/c/mediawiki/core/+/991408
[x] resources/src/mediawiki.libs.pluralruleparser https://gerrit.wikimedia.org/r/c/mediawiki/core/+/991408
[x] resources/src/mediawiki.watchstar.widgets https://gerrit.wikimedia.org/r/c/mediawiki/core/+/991658
[x] resources/src/mediawiki.widgets.visibleLengthLimit https://gerrit.wikimedia.org/r/c/mediawiki/core/+/991658 [Jon, CR: Anne ]
[x] resources/src/mediawiki.tempUserCreated https://gerrit.wikimedia.org/r/c/mediawiki/core/+/995268 [Jon]
[x] resources/src/mediawiki.searchSuggest https://gerrit.wikimedia.org/r/c/mediawiki/core/+/995267 [Jon]
[x] resources/src/mediawiki.libs.jpegmeta https://gerrit.wikimedia.org/r/c/mediawiki/core/+/995274 [Bartosz]
[x] resources/src/mediawiki.language [Anne] https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1002641
[x] resources/src/mediawiki.language.months [Anne] https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1002641
[x] resources/src/mediawiki.page.gallery.slideshow.js https://gerrit.wikimedia.org/r/c/mediawiki/core/+/995275 [Jon]
[x] resources/src/mediawiki.messagePoster https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1003046 [Anne]
[x] resources/src/mediawiki.jqueryMsg https://gerrit.wikimedia.org/r/c/mediawiki/core/+/988730 [Jon, CR: Roan]
[x] resources/src/mediawiki.widgets.datetime [Anne] https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1003785
[x] resources/src/mediawiki.ForeignApi (https://gerrit.wikimedia.org/r/c/mediawiki/core/+/983280) [Roan]
[x] resources/src/mediawiki.rcfilters https://gerrit.wikimedia.org/r/c/mediawiki/core/+/991655 [Jon, CR: Roan ]
[x] resources/src/mediawiki.htmlform.ooui [Jon] https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1004261
[x] resources/src/mediawiki.ForeignStructuredUpload.BookletLayout (https://gerrit.wikimedia.org/r/1003992) [Roan]
[x] resources/src/mediawiki.Upload.BookletLayout (https://gerrit.wikimedia.org/r/1003992) [Roan]
[x] resources/src/mediawiki.Upload.Dialog.js (https://gerrit.wikimedia.org/r/1003992) [Roan]
# Sign off steps
[x] Check https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1003046/3/resources/src/mediawiki.messagePoster/factory.js#113 was taken care of
# Files we didn't migrate
To do: For each of these, decide whether they should be excluded in the JSDoc config, documented, or marked with `@ignore` or `@private` tags
* [] resources/src/mediawiki.language.specialCharacters (exports JSON) https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1009368
* [] resources/src/mediawiki.notification.convertmessagebox.js (exports a function) https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1009369
* [] resources/src/mediawiki.special.apisandbox https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1009578
* [] resources/src/vue https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1009576
* [x] resources/src/codex (no longer exists) https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1008973
* [x] resources/src/codex-search (no longer exists) https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1008973
* [] resources/src/ooui-local.js https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1009368
* [] resources/src/mediawiki.router {T358813}
* [x] resources/src/qunitjs (CSS only)
* [] resources/src/oojs-global.js https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1009368
* [x] resources/src/skip-web2017-polyfills.js (used to prevent code loading for browsers that don't need it)
* [x] resources/src/mediawiki.inspect.js https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1009580
* [x] resources/src/mediawiki.special.preferences.ooui (ok to leave as-is)
* [] resources/src/moment https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1009372
* [x] resources/src/mediawiki.special.upload (private)