[MobileFrontend] Replace JSDuck with JSDoc
Closed, ResolvedPublic3 Story Points

Description

This will take some time, so the plan would be to chip away at this when time allows. It should not distract from more important sprint work. The task is mostly mechanical and potentially tedious but needs to be done!

To make progress, we will live with both jsduck and jsdoc temporarily until the migration is complete, merging as we go along.

  • Read http://usejsdoc.org/
  • Read http://usejsdoc.org/ and http://usejsdoc.org/about-configuring-jsdoc.html
  • Translate existing JSDuck configurations as wanted into new configuration files in MobileFrontend and MinervaNeue
  • Add temporary jsdoc script to package.json
  • Given a JavaScript file with a valid JSDoc commment, npm -s run jsdoc generates documentation in docs/
  • Replace JSDuck syntax with JSDoc syntax; if this is done over several passes, exclude the updated files from the JSDuck config
  • Give JSDuck and JSDoc the ol' switcheroo in MobileFrontend and MinervaNeue.

[x]le JSDuck is entirely scrubbed from the repo (includes rg jsduck and all JSDuck-syntax, package dependencies, etc).

  • Move jsdoc package.json script to doc

sign off steps

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptFeb 26 2018, 4:01 PM
Niedzielski renamed this task from Replace JSDuck with JSDoc to [MobileFrontend] [MinervaNeue] Replace JSDuck with JSDoc.
Jdlrobson updated the task description. (Show Details)Feb 28 2018, 6:29 PM
Jdlrobson triaged this task as Normal priority.
Jdlrobson added a subscriber: Jdlrobson.

Although tagged epic, Olga, it would be useful to chip away at this card bit by bit. It's likely a 8 or 13 pointer but can easily be divided across multiple sprints. How do we want to schedule this? This is causing friction internally as we develop so will make developers lives a lot easier if done sooner.

Jdlrobson removed a project: MinervaNeue.
Jdlrobson renamed this task from [MobileFrontend] [MinervaNeue] Replace JSDuck with JSDoc to [MobileFrontend] Replace JSDuck with JSDoc.

Change 446824 had a related patch set uploaded (by Niedzielski; owner: Stephen Niedzielski):
[mediawiki/skins/MinervaNeue@master] Hygiene: make JSDoc configs consistent

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

Change 446826 had a related patch set uploaded (by Niedzielski; owner: Stephen Niedzielski):
[mediawiki/extensions/Popups@master] Hygiene: make JSDoc configs consistent

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

Change 446829 had a related patch set uploaded (by Niedzielski; owner: Stephen Niedzielski):
[mediawiki/extensions/MobileFrontend@master] Hygiene: give JSDuck and JSDoc the ol' switcheroo

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

Change 447454 had a related patch set uploaded (by Niedzielski; owner: Stephen Niedzielski):
[integration/config@master] [MobileFrontend] Update: don't generate JSDuckumentation

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

Change 447454 abandoned by Niedzielski:
[MobileFrontend] Update: don't generate JSDuckumentation

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

Change 447454 restored by Niedzielski:
[MobileFrontend] Update: don't generate JSDuckumentation

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

Change 446824 merged by jenkins-bot:
[mediawiki/skins/MinervaNeue@master] Hygiene: make JSDoc configs consistent

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

Adding this to the sprint as it's happening alongside the Watchstar changes (T197133) so should go through our workflow.

Change 446826 merged by jenkins-bot:
[mediawiki/extensions/Popups@master] Hygiene: make JSDoc configs consistent

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

Change 448606 had a related patch set uploaded (by Niedzielski; owner: Stephen Niedzielski):
[mediawiki/extensions/MobileFrontend@master] Hygiene: fix mixin member JSDocs

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

ovasileva set the point value for this task to 3.Jul 30 2018, 5:27 PM
Niedzielski removed Jdlrobson as the assignee of this task.Aug 1 2018, 5:04 PM
Niedzielski claimed this task.

Change 447454 merged by jenkins-bot:
[integration/config@master] [MobileFrontend] [MinervaNeue] [Popups] Update: JavaScript documentation publishing

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

Jdlrobson updated the task description. (Show Details)Aug 3 2018, 3:04 AM

Change 449935 had a related patch set uploaded (by Jdlrobson; owner: Jdlrobson):
[mediawiki/extensions/MobileFrontend@master] Docs: Refresh README.md, split out frontend docs

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

Change 446829 merged by jenkins-bot:
[mediawiki/extensions/MobileFrontend@master] Hygiene: give JSDuck and JSDoc the ol' switcheroo

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

Change 448606 merged by jenkins-bot:
[mediawiki/extensions/MobileFrontend@master] Hygiene: fix mixin member JSDocs

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

I've merged most of the patches. Please review https://gerrit.wikimedia.org/r/449935
We've also broken the public docs: https://doc.wikimedia.org/MobileFrontend/master/js/
We should fix this ASAP.

Change 450229 had a related patch set uploaded (by Niedzielski; owner: Stephen Niedzielski):
[integration/config@master] [MobileFrontend] [MinervaNeue] [Popups] Fix: JavaScript documentation destination

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

Niedzielski removed Niedzielski as the assignee of this task.Aug 3 2018, 7:34 PM
Niedzielski removed a subscriber: Niedzielski.
Niedzielski added a subscriber: Niedzielski.

Moved to blocked on others based on review needed from RelEng.

Change 450635 had a related patch set uploaded (by Niedzielski; owner: Stephen Niedzielski):
[integration/config@master] [MobileFrontend] [MinervaNeue] [Popups] Update: promote JSDocs to postmerge

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

Change 450229 merged by jenkins-bot:
[integration/config@master] [MobileFrontend] [MinervaNeue] [Popups] Fix: JavaScript documentation destination

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

What needs code review here?
I see https://doc.wikimedia.org/MobileFrontend/master/js/ is working again as planned. Should this be moved to sign off?

It sounds like you're happy with it so I will ping RelEng on https://gerrit.wikimedia.org/r/#/c/integration/config/+/450635/.

It sounds like you're happy with it so I will ping RelEng on https://gerrit.wikimedia.org/r/#/c/integration/config/+/450635/.

Did this happen? Looks like the patch needs a rebase and Jenkins is unhappy.

@Jdlrobson, thanks! I've rebased the patch.

Change 450635 merged by jenkins-bot:
[integration/config@master] [MobileFrontend] [MinervaNeue] [Popups] Update: promote JSDocs to postmerge

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

I pushed a patch and @nray merged it to make DownloadIcon a class. I will resolve this task when I see evidence in the published docs that this shows up.

Jdlrobson closed this task as Resolved.Aug 21 2018, 12:47 AM

w00t

Change 449935 abandoned by Jdlrobson:
Docs: Refresh README.md, split out frontend docs

Reason:
I can't remember what I was doing here it was so long ago.

We need to find a better way of making docs changes incrementally. The current docs are terrible.

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