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
Hi everyone,
Here's an update on where we are with the migration to JSDoc.
== Migrating MediaWiki core to JSDoc == We have completed migrating almost all the files in MediaWiki core[0]. We're currently working through code review for the last few patches, completing a final review of the docs, and identifying follow-up work[1].
== Migrating other codebases == Since December, two projects (OOUI and EventLogging) have migrated to JSDoc, but there are still 7 projects that need to migrate. See the parent task[2] for a list of those projects and the migration guide. Feel free to reach out if you need help migrating a project.
== Improving the JSDoc WMF theme == Since December, we've released 5 minor versions of the theme with 45 fixes and enhancements[3]. We're currently working through our remaining backlog[4], and we plan to release v1.0 of the theme at the end of March.
== Request for feedback == We'd love to hear from you on the wiki page[5]: - What's missing from the documentation[0] that's important to you? - What issues do you notice with the existing documentation? - How can we improve the documentation?
A huge thank you to everyone who has helped with this project and provided feedback so far!
[0]: https://doc.wikimedia.org/mediawiki-core/master/js/ [1]: https://phabricator.wikimedia.org/T352308 [2]: https://phabricator.wikimedia.org/T138401 [3]: https://gerrit.wikimedia.org/r/plugins/gitiles/jsdoc/wmf-theme/+/refs/heads/... [4]: https://phabricator.wikimedia.org/T187672 [5]: https://www.mediawiki.org/wiki/Talk:JSDoc_WMF_theme
On Wed, Dec 6, 2023 at 11:54 AM Alexandra Paskulin apaskulin@wikimedia.org wrote:
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
[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
wikitech-l@lists.wikimedia.org