Skip to content

[JS] Migrate from TypeScript to JSDoc

Phuedx requested to merge jsdoc into main

Using TypeScript for required type checking has its advantages but has one key disadvantage for us (Data Platform): some TypeScript type definitions cannot be parsed by JSDoc.

Both the JS Metrics Platform Client (JS MPC) and the primary target codebase for it, the EventLogging MediaWiki Extension (EventLogging), use JSDoc to automatically generate documentation. Since TypeScript type definitions cannot be parsed by JSDoc, we exclude the JS MPC from EventLogging's documentation, leaving the documentation very short on detail, including for "core" methods, e.g. mw.eventLog.submit(), borrowed from the JS MPC. This was noted by Alex Paskulin in T372682#10173644.

Migrating all type definitions from TypeScript to JSDoc loses some type checking power, which will likely have to be made up with additional test coverage. However, it means that we can automatically generate a complete documentation site from either this codebase or EventLogging, which will benefit the users of our software.

Edited by Phuedx

Merge request reports