Page MenuHomePhabricator

Fix public documentation for mw.eventLog.submit() and dispatch()
Closed, ResolvedPublic5 Estimated Story Points

Description

Background

In https://gerrit.wikimedia.org/r/c/mediawiki/extensions/EventLogging/+/754002 we replaced mw.eventLog.submit() with the Client Library implementation of submit and introduced .dispatch(), which is now deprecated. Regrettably, the same patch broke the public documentation for both methods.

Unfortunately, EventLogging uses JSDuck, which can't process the DocBlocks in the JS Client Library. AFAICT we have two options to fix the documentation:

  1. Copy the DocBlocks for MetricsClient#submit() and #dispatch() into EventLogging (here and here)
  2. Update EventLogging to use JSDoc and use @borrows tags to automatically copy the DocBlocks for MetricsClient#submit() and #dispatch() when the documentation is built and published

1 has the risk that the documentation for the mw.eventLog and MetricsClient methods could drift but would be significantly quicker than 2.

AC

Event Timeline

Restricted Application added a subscriber: Aklapper. · View Herald Transcript
phuedx updated the task description. (Show Details)

EventLogging uses JSDuck, which can't process the DocBlocks in the JS Client Library

It looks like JSDuck is configured to exclude the files in modules/lib. I wasn't able to test this locally (Ruby issues), but as a short term solution, you could try including those files and using @inheritdoc.

Update EventLogging to use JSDoc

This is definitely something that should happen at some point as part of the project to migrate off of JSDuck (T138401), but there will be some work needed to update the tags to work with JSDoc. I did a quick test locally, and it looks like JSDoc's @borrows would fix the issue here. Let me know when you're interested in starting the process to migrate to JSDoc, and I can open a patch to get it started.

@apaskulin We are interested now! Thank you very much for your help!

phuedx set the point value for this task to 5.Feb 13 2024, 12:33 PM

Great! I've opened T357444: Migrate EventLogging to JSDoc. I can open a WIP patch to get it started by the end of the week, but feel free to claim the task and start sooner if you'd like.

I've opened a patch for T357444: Migrate EventLogging to JSDoc, just need someone familiar with the extension (and particularly the MetricsClient) to do the review. To run the docs locally, see the instructions at https://gerrit.wikimedia.org/g/jsdoc/wmf-theme#local-development

This was done by @apaskulin as part of the patch for T357444: Migrate EventLogging to JSDoc.

The DocBlock for mw.eventLog.submit() is visible and borrowed from MetricsClient#submit() and the same is true for mw.eventLog.dispatch(). The latter is also correctly marked as deprecated.

phuedx updated the task description. (Show Details)