Split from T138401: Replace jsduck with JSDoc3 across all Wikimedia code bases.
This is currently blocking us from using es6 features like const in the parts of the code that are covered by jsduck.
We should also use this moment to reconsider whether we actually get use out of that documentation. Neither WikibaseLexeme nor EntitySchema has generated JavaScript documentation.
| Status | Subtype | Assigned | Task | ||
|---|---|---|---|---|---|
| Open | Feature | None | T263914 Offer TypeScript declaration files for the MediaWiki Javascript API (MediaWiki API typings) | ||
| Resolved | hashar | T213282 JSDuck at doc.wikimedia.org loads fonts from google | |||
| Open | None | T334853 Clean up JS code now that we can use ES6 rather than ES5 across all Wikimedia deployed codebases | |||
| Stalled | None | T363905 Uninstall jsduck and related material from CI images etc., once it's no longer needed | |||
| Resolved | apaskulin | T138401 Replace jsduck with JSDoc3 across all Wikimedia code bases | |||
| Open | None | T342905 Replace jsduck with JSDoc3 in Wikibase |
We should also use this moment to reconsider whether we actually get use out of that documentation.
Apparently it was a fourth birthday present by Jonas and Amir: T133028: [Story] autogenerated Wikibase documentation (and integration/config changes). That said, the link search results all seem to be related to that birthday announcement – I’m not seeing any pages that look like they link to the JS documentation independently for its usefulness.
(The REST API docs under js/rest-api/ are built separately, and I think we could still continue to build those if we stop building the rest of the JS documentation.)
Hi all, Wikibase is the last Wikimedia codebase to start migrating away from JSDuck, so I wanted to reach out and see if there's anything I can do to help.
I ran JSDoc on Wikibase locally, and unfortunately it looks like the process to set up a JSDoc equivalent of the JSDuck site won't be quick. JSDoc doesn't infer the structure of the code as well as JSDuck does, so we would need to add a lot of annotations that specify the structure. For example, in order to specify that an event belongs to a certain class. At first glance, we'd probably need to add these structural annotations in hundreds of places to fully replicate the existing JSDuck site.
As Lucas mentioned, one option is to stop building a JS docs site for Wikibase entirely. Another data point to add here is that the JSDuck site isn't currently linked from the doc.wikimedia.org homepage.
A middle ground option could be to set up a JSDoc site for only the public-facing parts of the Wikibase JS API that are meant to be used by gadget and extension developers. This would reduce the scope of the migration and make it more feasible.
It’s not my decision, but given that we haven’t made any progress here in over a year, my vote is for dropping these docs completely and only keeping js/rest-api/ around.
A middle ground option could be to set up a JSDoc site for only the public-facing parts of the Wikibase JS API that are meant to be used by gadget and extension developers.
I think the closest thing we have to that is Hooks JS (which is part of the Doxygen-built PHP docs and thus unaffected). In general, our JS code is not considered a stable interface, so I wouldn’t expect any intentionally public-facing documentation in the JSDuck output that we would need to preserve.
WMDE prefers to not maintain the reference docs mentioned here over the effort of migrating those to other tooling. I am not sure why it was not communicated here June, I would have expected myself to have said that earlier.
Change #1088536 had a related patch set uploaded (by WMDE-leszek; author: WMDE-leszek):
[mediawiki/extensions/Wikibase@master] Drop npm script to generate jsduck docs
Change #1088559 had a related patch set uploaded (by WMDE-leszek; author: WMDE-leszek):
[mediawiki/extensions/Wikibase@master] Removed jsduck configuration file
Change #1088536 merged by jenkins-bot:
[mediawiki/extensions/Wikibase@master] Drop npm script to generate jsduck docs