Page MenuHomePhabricator

Migrate JavaScript API documentation from jsduck to JSDoc
Closed, ResolvedPublic3 Estimated Story Points

Description

jsdoc is no longer used in other Web repos such as MobileFrontend (see T138401). Migrate the existing Vector JavaScript docs to JSDoc.

Acceptance criteria

  • Translate the existing jsduck configuration as wanted into a new JSDoc configuration file. See MobileFrontend and the official documentation for reference. Sharing the same configuration among projects would be nice but is out of scope for this task!
  • Revise the NPM package.json file to use JSDoc not jsduck. Given a JavaScript file with a valid JSDoc comment, npm -s run jsdoc generates documentation in docs/. See MobileFrontend for an example script and update to .gitignore.
  • There's not much JavaScript in Vector but any existing jsduck documentation should be revised to JSDocs. An effort to accurately type inputs and outputs would be a helpful improvement but is not a requirement for completion of this task.
  • Add Vector documentation to doc.wikimedia.org so everyone can participate. See the MobileFrontend configuration for an example.
  • jsduck is entirely scrubbed from the repo (includes rg jsduck and all jsduck-syntax, package dependencies, etc).
  • Use jsdoc-wmf-theme

QA

Event Timeline

@ovasileva, I think this task and its parent are very important for any JavaScript work we do in Vector. I would rather not have to lookup jsduck syntax :] Would it be possible to get this into the kanbanana soon?

ovasileva triaged this task as Medium priority.Dec 4 2019, 10:39 AM

@ovasileva, I think this task and its parent are very important for any JavaScript work we do in Vector. I would rather not have to lookup jsduck syntax :] Would it be possible to get this into the kanbanana soon?

moved to needs analysis

ovasileva set the point value for this task to 3.Dec 4 2019, 5:24 PM

Change 571841 had a related patch set uploaded (by Nray; owner: Nray):
[mediawiki/skins/Vector@master] 🚿 Hygiene: Replace 🦆 JSDuck with 📄 JSDoc

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

https://gerrit.wikimedia.org/r/571841 is ready for review which replaces the duck with the doc.

I plan to add another patch for documenting more input/output types in Vector, but ^^ is ready for review now

Change 572127 had a related patch set uploaded (by Nray; owner: Nray):
[mediawiki/skins/Vector@master] Add 'jsdoc-wmf-theme' to jsdoc

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

Change 571841 merged by jenkins-bot:
[mediawiki/skins/Vector@master] build: Replace JSDuck with JSDoc

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

I think this can skip QA - it's on https://doc.wikimedia.org/mediawiki-skins-Vector/master/js/js/ but I think we should verify that all the jsdocumented code is showing up there before sign off.

Talking to @Volker_E there might be an issue with using jsdoc theme right now so we might need to break that out into a separate task.

nray subscribed.
Niedzielski assigned this task to nray.
Niedzielski updated the task description. (Show Details)

Change 572127 abandoned by Nray:
Add 'jsdoc-wmf-theme' to jsdoc

Reason:
Abandoning for now to avoid extra noise. It's a small enough change, that it will be easy to reopen if necessary

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

Change 572127 restored by Nray:
Add 'jsdoc-wmf-theme' to jsdoc

Reason:
I've added this as a topic for discussion in the Web team's next super-happy-dev-time meeting

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

Change 572127 merged by jenkins-bot:
[mediawiki/skins/Vector@master] Add 'jsdoc-wmf-theme' to jsdoc

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