Hi everyone,
tl;dr The tools we use to document Wikimedia JavaScript code are changing.
In the short term, you can read the complete MediaWiki core JavaScript docs
using the 1.41 version[0] while we migrate to the new system[1]. If you use
JavaScript documentation on
doc.wikimedia.org, please share your feedback
on wiki[2].
Wikimedia JavaScript codebases are switching from using JSDuck[3] to
JSDoc[4] for documentation. Started in 2016, this migration is necessary
because JSDuck is currently unmaintained and does not support the ES6
standard[5]. Several Wikimedia JavaScript codebases, including Vector and
GlobalWatchlist, already use JSDoc, while several others, such as
VisualEditor and MediaWiki core, still use JSDuck.
The migration project consists of two parts: changing the codebases to
support JSDoc and improving the usability of the JSDoc WMF theme. For more
information, see phab:T138401[6].
== Migrating MediaWiki core to JSDoc ==
We are migrating MediaWiki core to JSDoc incrementally. While the migration
is in progress, the master branch docs will be incomplete, containing only
those modules that have been migrated. To read the old JSDuck docs, see the
MediaWiki 1.41 docs[0].
To help with migration, choose a module from the list in phab:T352308[7],
and follow the guide on phab:T138401[6] to translate the tags from JSDuck
to JSDoc.
== Migrating other codebases ==
You can find a list of codebases that use JSDuck on phab:T138401[6].
(Please add any that are missing.) To help migrate a codebase that uses
JSDuck, follow the instructions to set up JSDoc[8], and use the guide in
phab:T138401[6] to translate the tags from JSDuck to JSDoc.
== Improving the JSDoc WMF theme ==
One of the biggest differences between JSDuck and JSDoc is the HTML
interface for reading the docs. The WMF theme for JSDoc is not as
full-featured as the JSDuck theme, but to support this migration, the
Wikimedia Foundation Web, Design Systems, and Technical Documentation teams
are working to prioritize and complete a set of improvements to the JSDoc
theme, with the goal of releasing version 1 of jsdoc-wmf-theme in 2024.
If you use JavaScript documentation on
doc.wikimedia.org, please leave a
comment on the JSDoc WMF theme talk page[2] and let us know how you use the
docs and which features of the theme are the most important to you.
Thank you for reading!
Alex, Kamil, Jon, Roan, and Anne
[0]:
https://doc.wikimedia.org/mediawiki-core/REL1_41/js/
[1]:
https://doc.wikimedia.org/mediawiki-core/master/js/
[2]:
https://www.mediawiki.org/wiki/Talk:JSDoc_WMF_theme
[3]:
https://github.com/senchalabs/jsduck
[4]:
https://en.wikipedia.org/wiki/JSDoc
[5]
https://en.wikipedia.org/wiki/ECMAScript
[6]:
https://phabricator.wikimedia.org/T138401
[7]:
https://phabricator.wikimedia.org/T352308
[8]:
https://www.mediawiki.org/wiki/JSDoc
--
Alex Paskulin
Technical Writer
Wikimedia Foundation