Page MenuHomePhabricator

Replace jsduck with JSDoc3 in GuidedTour
Open, Needs TriagePublic

Description

  • make sure CI isn't broken (sign of an abandoned extension)
  • get JSDoc + jsdoc-wmf-theme installed, with npm run jsdoc working and /docs/js viewable
  • compare it to JSDuck site, make sure it's identical, fix anything as needed. check both left menu and homepage. homepage has some extra stuff on it that isn't in the left menu
  • create / make sure it has a readme, in markdown. make sure the readme links to the extension on mediawiki.org
  • switch JSDuck for JSDoc on doc.wikimedia.org (by switching npm run doc to jsdoc. after that it will deploy instantly and the cache will clear in an hour)
  • delete any remaining JSDuck code
  • add && npm run doc to the npm test script

Event Timeline

Change #1043786 had a related patch set uploaded (by Novem Linguae; author: Novem Linguae):

[mediawiki/extensions/GuidedTour@master] JSDoc: initial setup

https://gerrit.wikimedia.org/r/1043786

Hmm, that's interesting. In this patch, I got the /docs/js/ site to build, and most of it works, but when I click on mw.guidedTour, I get a 404 error.

An examination of the directory structure shows the weird file mw.html#.guidedTour instead of the expected mw.guidedTour.html. Ever seen this before @apaskulin? Note that it still does this when I turn off jsdoc-wmf-theme.

image.png (1×793 px, 109 KB)

image.png (576×1 px, 43 KB)

image.png (561×1 px, 29 KB)

Looks like this is caused by https://gerrit.wikimedia.org/g/mediawiki/extensions/GuidedTour/+/master/modules/ext.guidedTour.lib/ext.guidedTour.lib.TransitionEvent.js#79 which JSDoc is interpreting as a property named guidedTour belonging to the class mw, which then conflicts with the class named mw.guidedTour. Adding @ignore to that docblock fixes the issues and causes mw.guidedTour.html to generate correctly.

I'm not totally sure what the best way is to fix this. Looking at these properties in JSDuck, they seem to be properties for a private method, so maybe adding @ignore to the docblock causing the issue would be fine.