Page MenuHomePhabricator

Improve Minerva skin documentation
Closed, DeclinedPublic

Description

The MinervaNeue skin was extracted from MobileFrontend extension. The JS documentation requires some polishing as currently, it is pretty difficult to read Minerva docs.

Current documentation can be generated by running npm run-script doc.

Developer notes

Probably the best approach would be to spend a set amount of hours instead of a set of acceptance criteria. Currently, only NotificationButton and MainMenu are documented.

Event Timeline

pmiazga created this task.Jul 20 2017, 7:35 PM
Restricted Application added subscribers: TerraCodes, Aklapper. · View Herald TranscriptJul 20 2017, 7:35 PM
Jdlrobson closed this task as Declined.Jul 20 2017, 10:15 PM
Jdlrobson moved this task from Incoming to Needs Prioritization on the Readers-Web-Backlog board.

Currently, only NotificationButton and MainMenu are documented.

That's because they are the only classes provided by MinervaNeue. All other code are private functions.

I don't think the MinervaNeue js documentation is actually that useful as all it does is initialise things.
All the interesting code currently still lives in MobileFrontend.

MinervaNueue has 21 script files, it worries me a bit that documentation is so small, almost all of those private functions have proper documentation. I was expecting a bit more than just two classes.

I think we're conflating two things.

  1. The existence of documentation inside the code
  2. The documentation we show when we run make docs

In MinervaNeue I think the important thing is the existence.

We do not publish documentation for Minerva here: https://docs.wikimedia.org
The important thing is developers reading the code can understand it.
jsduck is used not to create readable doc files but to ensure we add documentation to our code.

We can remove the @ignore tag if that's useful... that would make the output documentation larger, but I'd argue that the output documentation is not useful.

Thoughts?