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

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptNov 26 2019, 5:56 PM

@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
MSantos added a subscriber: MSantos.Jan 6 2020, 3:49 PM
Jdlrobson moved this task from Backlog to Technical on the Vector board.Jan 15 2020, 5:58 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

nray added a comment.Feb 13 2020, 12:45 AM

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

Volker_E updated the task description. (Show Details)Feb 13 2020, 5:34 PM

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.

Jdlrobson updated the task description. (Show Details)Feb 14 2020, 7:13 PM
nray removed nray as the assignee of this task.Feb 14 2020, 7:44 PM
nray added a subscriber: nray.

@Niedzielski or @Jdrewniak - can one of you sign this off?

Niedzielski closed this task as Resolved.Feb 18 2020, 3:31 PM
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