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/master/HISTORY.md [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 <[email protected]> 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 > > [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 > -- Alex Paskulin Technical Writer Wikimedia Foundation
_______________________________________________ Wikitech-l mailing list -- [email protected] To unsubscribe send an email to [email protected] https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/
