Page MenuHomePhabricator

Port remaining files to jsdoc in MediaWiki core
Closed, ResolvedPublic

Description

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

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, 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 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.
  7. 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

Phase 2

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.

  • resources/src/mediawiki.page.image.pagination.js
  • resources/src/mediawiki.page.media.js
  • resources/src/mediawiki.special.block.js
  • resources/src/mediawiki.page.gallery.js
  • resources/src/mediawiki.userSuggest.js
  • resources/src/mediawiki.special.userrights.js
  • resources/src/mediawiki.special.search.commonsInterwikiWidget.js
  • resources/src/mediawiki.special.contributions.js
  • resources/src/mediawiki.checkboxtoggle.js
  • resources/src/mediawiki.special.changeslist.legend.js
  • resources/src/mediawiki.special.changeemail.js
  • resources/src/mediawiki.special.changecredentails.js
  • resources/src/mediawiki.misc-authed-pref
  • resources/src/mediawiki.toc
  • resources/src/mediawiki.pulsatingdot
  • resources/src/mediawiki.skinning
  • resources/src/mediawiki.special
  • resources/src/mediawiki.action
  • resources/src/mediawiki.action.edit
  • resources/src/mediawiki.special.changeslist
  • resources/src/mediawiki.apipretty
  • resources/src/mediawiki.special.changeslist.watchlistexpiry
  • resources/src/mediawiki.special.createaccount
  • resources/src/mediawiki.special.editrecovery
  • resources/src/mediawiki.special.search
  • resources/src/mediawiki.diff
  • resources/src/mediawiki.special.unwatchedPages
  • resources/src/mediawiki.editRecovery
  • resources/src/mediawiki.filewarning
  • resources/src/mediawiki.special.watchlist
  • resources/src/mediawiki.helplink
  • resources/src/mediawiki.htmlform
  • resources/src/mediawiki.tempUserBanner
  • resources/src/mediawiki.language.names
  • resources/src/mediawiki.misc-authed-curate
  • resources/src/mediawiki.misc-authed-ooui

Phase 4

Sign off steps

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

Details

SubjectRepoBranchLines +/-
mediawiki/coremaster+7 -1
mediawiki/coremaster+0 -8
mediawiki/coremaster+5 -2
mediawiki/coremaster+41 -55
mediawiki/coremaster+22 -12
mediawiki/coremaster+1 -0
mediawiki/coremaster+19 -4
mediawiki/coremaster+0 -2
mediawiki/coremaster+1 -0
mediawiki/coremaster+102 -92
mediawiki/coremaster+38 -3
mediawiki/coremaster+275 -204
mediawiki/coremaster+24 -19
mediawiki/coremaster+3 -13
mediawiki/coremaster+4 -4
mediawiki/coremaster+16 -9
mediawiki/coremaster+143 -105
mediawiki/coremaster+39 -22
mediawiki/coremaster+164 -93
mediawiki/coremaster+100 -68
mediawiki/coremaster+11 -1
mediawiki/coremaster+2 -2
mediawiki/coremaster+23 -21
mediawiki/coremaster+20 -2
mediawiki/coremaster+0 -0
mediawiki/coremaster+37 -50
mediawiki/coremaster+34 -4
mediawiki/coremaster+38 -6
mediawiki/coremaster+13 -0
mediawiki/coremaster+1 -0
mediawiki/coremaster+40 -40
mediawiki/coremaster+3 -3
mediawiki/coremaster+10 -2
mediawiki/coremaster+67 -66
mediawiki/coremaster+31 -15
mediawiki/coremaster+45 -98
mediawiki/coremaster+210 -197
mediawiki/coremaster+79 -50
mediawiki/coremaster+25 -13
mediawiki/coremaster+53 -10
mediawiki/coremaster+60 -104
mediawiki/coremaster+65 -41
mediawiki/coremaster+0 -6
mediawiki/coremaster+10 -8
mediawiki/coremaster+2 -2
mediawiki/coremaster+27 -12
mediawiki/coremaster+0 -161
mediawiki/coremaster+56 -13
mediawiki/coremaster+49 -27
mediawiki/coremaster+61 -43
mediawiki/coremaster+1 -2
mediawiki/coremaster+26 -34
mediawiki/coremaster+121 -191
mediawiki/coremaster+0 -5
mediawiki/coremaster+60 -0
mediawiki/coremaster+15 -15
mediawiki/coremaster+62 -49
mediawiki/coremaster+44 -43
mediawiki/coremaster+28 -22
mediawiki/coremaster+15 -11
mediawiki/coremaster+8 -12
mediawiki/coremaster+13 -11
mediawiki/coremaster+15 -13
mediawiki/coremaster+218 -135
Show related patches Customize query in gerrit

Related Objects

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes

Change 1003015 had a related patch set uploaded (by Jdlrobson; author: Jdlrobson):

[mediawiki/core@master] Documentation: Namespace searchSuggest types

https://gerrit.wikimedia.org/r/1003015

Change 1002641 merged by jenkins-bot:

[mediawiki/core@master] mw.language: Document in JSDoc

https://gerrit.wikimedia.org/r/1002641

Jdlrobson updated the task description. (Show Details)

Change 1003015 merged by jenkins-bot:

[mediawiki/core@master] Documentation: Namespace searchSuggest types

https://gerrit.wikimedia.org/r/1003015

Change 1003046 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[mediawiki/core@master] mw.messagePoster: Document in JSDoc

https://gerrit.wikimedia.org/r/1003046

Change 995275 merged by jenkins-bot:

[mediawiki/core@master] Documentation: mediawiki.page.gallery.slideshow

https://gerrit.wikimedia.org/r/995275

Change 997949 abandoned by Jdlrobson:

[mediawiki/core@master] Documentation: Add check for jsdoc

Reason:

See https://phabricator.wikimedia.org/T357489

https://gerrit.wikimedia.org/r/997949

Change 1003046 merged by jenkins-bot:

[mediawiki/core@master] mw.messagePoster: Document in JSDoc

https://gerrit.wikimedia.org/r/1003046

Change 988730 merged by jenkins-bot:

[mediawiki/core@master] Documentation: $.msg (mediawiki.jqueryMsg)

https://gerrit.wikimedia.org/r/988730

Change 1003785 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[mediawiki/core@master] mediawiki.widgets.datetime: Migrate to JSDoc

https://gerrit.wikimedia.org/r/1003785

Change 1003785 merged by jenkins-bot:

[mediawiki/core@master] mediawiki.widgets.datetime: Migrate to JSDoc

https://gerrit.wikimedia.org/r/1003785

Change 1003992 had a related patch set uploaded (by Catrope; author: Catrope):

[mediawiki/core@master] docs; Convert mw.Upload.Dialog and friends to jsdoc

https://gerrit.wikimedia.org/r/1003992

Change 983280 merged by jenkins-bot:

[mediawiki/core@master] documentation: Convert mediawiki.ForeignApi from jsduck to jsdoc

https://gerrit.wikimedia.org/r/983280

Change 1004261 had a related patch set uploaded (by Jdlrobson; author: Jdlrobson):

[mediawiki/core@master] Document mediawiki.htmlform.ooui classes

https://gerrit.wikimedia.org/r/1004261

The textSelection methods are marked as private and thus not showing up in the documentation. They should be surfaced one way or another as they are APIs meant to be used by consumers.

Change 1005823 had a related patch set uploaded (by Alex Paskulin; author: Alex Paskulin):

[mediawiki/core@master] docs: Fix JSDoc descriptions

https://gerrit.wikimedia.org/r/1005823

Change 1005823 merged by jenkins-bot:

[mediawiki/core@master] docs: Fix JSDoc descriptions

https://gerrit.wikimedia.org/r/1005823

Change 1005832 had a related patch set uploaded (by Alex Paskulin; author: Alex Paskulin):

[mediawiki/core@master] docs: Deduplicate JSDoc tags for mw.language

https://gerrit.wikimedia.org/r/1005832

The documentation for the textSelection methods are marked as private and thus not showing up. They should be surfaced one way or another as they are APIs meant to be used by consumers.

I created T358290 so this doesn't get lost. Thanks for the report!

Change 1005832 merged by jenkins-bot:

[mediawiki/core@master] docs: Deduplicate JSDoc tags for mw.language

https://gerrit.wikimedia.org/r/1005832

Can you re-surface mw.loader.addStyleTag()? It's been quite handy, it's used a lot, and the doc for mw.util.addCSS() even mentions it as an alternative.

Can you re-surface mw.loader.addStyleTag()? It's been quite handy, it's used a lot, and the doc for mw.util.addCSS() even mentions it as an alternative.

Thanks for the report! I've opened T358391 for this.

Hey Roan seems like all work here is on you (and then me once the patches have been resubmitted). Please assign to me when you've reviewed my patch and posted up new versions of your patch so we can get this over the finish line.

Change 1006130 had a related patch set uploaded (by Tacsipacsi; author: Tacsipacsi):

[mediawiki/core@master] docs: Various JSDoc fixes

https://gerrit.wikimedia.org/r/1006130

FYI, I added support to Patch demo to generate the JSDoc documentation as well, to make these patches easier to test and review: https://gitlab.wikimedia.org/repos/ci-tools/patchdemo/-/merge_requests/603. There will be a link to the generated documentation on the main page of every new wiki. For example: https://patchdemo.wmflabs.org/wikis/147380bd91. (I hope it's better late than never :) )

Change 1006130 merged by jenkins-bot:

[mediawiki/core@master] docs: Various JSDoc fixes

https://gerrit.wikimedia.org/r/1006130

FYI, I added support to Patch demo to generate the JSDoc documentation as well, to make these patches easier to test and review: https://gitlab.wikimedia.org/repos/ci-tools/patchdemo/-/merge_requests/603. There will be a link to the generated documentation on the main page of every new wiki. For example: https://patchdemo.wmflabs.org/wikis/147380bd91. (I hope it's better late than never :) )

This is awesome! Thanks, @matmarex! I've added a note about this to the wiki page.

Change 991655 merged by jenkins-bot:

[mediawiki/core@master] Document rcfilters

https://gerrit.wikimedia.org/r/991655

Change 1004261 merged by jenkins-bot:

[mediawiki/core@master] Document mediawiki.htmlform.ooui classes

https://gerrit.wikimedia.org/r/1004261

Change 1007457 had a related patch set uploaded (by Alex Paskulin; author: Alex Paskulin):

[mediawiki/core@master] docs: Hide Events section in JSDoc

https://gerrit.wikimedia.org/r/1007457

Test wiki created on Patch demo by APaskulin (WMF) using patch(es) linked to this task:
https://patchdemo.wmflabs.org/wikis/9395d1c804/w

Jdlrobson updated the task description. (Show Details)

The epic part of this is now done! Assigning to you to go over the fruits of our labour and to create new follow up tickets for any issues that remain in the documentation.

This might also be a good time to check in with the community and ask the question:

  • What's missing from the documentation that's important to you?
  • What issues do you notice with the existing documentation?
  • How can we improve on the documentation?

Change 1003992 merged by jenkins-bot:

[mediawiki/core@master] docs: Convert mw.Upload.Dialog and friends to jsdoc

https://gerrit.wikimedia.org/r/1003992

Change 1007457 abandoned by Alex Paskulin:

[mediawiki/core@master] docs: Hide Events section in JSDoc

Reason:

Per review comments

https://gerrit.wikimedia.org/r/1007457

Change 1008973 had a related patch set uploaded (by Alex Paskulin; author: Alex Paskulin):

[mediawiki/core@master] docs: Remove files that no longer exist

https://gerrit.wikimedia.org/r/1008973

Change 1008973 merged by jenkins-bot:

[mediawiki/core@master] docs: Remove files that no longer exist

https://gerrit.wikimedia.org/r/1008973

Change 1009368 had a related patch set uploaded (by Alex Paskulin; author: Alex Paskulin):

[mediawiki/core@master] docs: Include files without JSDoc comments

https://gerrit.wikimedia.org/r/1009368

Change 1009369 had a related patch set uploaded (by Alex Paskulin; author: Alex Paskulin):

[mediawiki/core@master] docs: Migrate convertmessagebox to JSDoc

https://gerrit.wikimedia.org/r/1009369

Change 1009372 had a related patch set uploaded (by Alex Paskulin; author: Alex Paskulin):

[mediawiki/core@master] docs: Include moment in JSDoc

https://gerrit.wikimedia.org/r/1009372

Change 1009576 had a related patch set uploaded (by Alex Paskulin; author: Alex Paskulin):

[mediawiki/core@master] docs: Migrate Vue wrapper to JSDoc

https://gerrit.wikimedia.org/r/1009576

Change 1009578 had a related patch set uploaded (by Alex Paskulin; author: Alex Paskulin):

[mediawiki/core@master] docs: Migrate ApiSandbox to JSDoc

https://gerrit.wikimedia.org/r/1009578

Change rEOAU1009580050bf had a related patch set uploaded (by Alex Paskulin; author: Alex Paskulin):

[mediawiki/core@master] docs: Migrate mw.inspect to JSDoc

https://gerrit.wikimedia.org/r/1009580

Change rEOAU1009580050bf merged by jenkins-bot:

[mediawiki/core@master] docs: Migrate mw.inspect to JSDoc

https://gerrit.wikimedia.org/r/1009580

Test wiki created on Patch demo by APaskulin (WMF) using patch(es) linked to this task:
https://patchdemo.wmflabs.org/wikis/af1f262be9/w

Change 1009578 merged by jenkins-bot:

[mediawiki/core@master] docs: Remove ApiSandbox class page from JSDoc

https://gerrit.wikimedia.org/r/1009578

Change 1009576 merged by jenkins-bot:

[mediawiki/core@master] docs: Migrate Vue wrapper to JSDoc

https://gerrit.wikimedia.org/r/1009576

Change 1009369 merged by jenkins-bot:

[mediawiki/core@master] docs: Migrate convertmessagebox to JSDoc

https://gerrit.wikimedia.org/r/1009369

Change 1009372 merged by jenkins-bot:

[mediawiki/core@master] docs: Include moment in JSDoc

https://gerrit.wikimedia.org/r/1009372

Change 1013131 had a related patch set uploaded (by Alex Paskulin; author: Alex Paskulin):

[mediawiki/core@master] docs: Fix module docs in JSDoc

https://gerrit.wikimedia.org/r/1013131

Change #1009368 merged by jenkins-bot:

[mediawiki/core@master] docs: Remove remaining jsdoc exclusions

https://gerrit.wikimedia.org/r/1009368

Change #1013131 merged by jenkins-bot:

[mediawiki/core@master] docs: Fix module docs in JSDoc

https://gerrit.wikimedia.org/r/1013131

apaskulin moved this task from Backlog to Done on the Tech-Docs-Team board.

All files have been migrated to JSDoc and the review has been completed 🎉 Further work will be handled in separate tasks. Thanks to everyone who contributed! Check out the fully migrated docs: https://doc.wikimedia.org/mediawiki-core/master/js/