Page MenuHomePhabricator

mobile-html: finalize PCS client JS interface
Closed, ResolvedPublic

Description

Background information

The PCS client JS interface (anything in the pcs.c1.* namespace) was adjusted as clients began implementation and requested changes. Any now-unused public functions should be removed and the supported interface should be finalized.

What

  • Work with the apps teams to determine which functionality they no longer need (like Page.setup?)
  • Finalize the interface by removing any unused functionality
  • Decide a documentation strategy for the interface (JSDoc, Swagger, keep updating pcs.md, others?) and make documentation easy to generate and publicly available

Potentially unused functionality

  • FooterTransformer

Acceptance criteria

  • pcs.c1.* interface is finalized
  • Documentation for pcs.c1.* is publicly available
  • Documentation for pcs.c1.* is easy to generate from code comments
  • Update the markdown tutorial/docs on page library pagelib/docs/pcs/pcs.md

Event Timeline

I would like to have a Documentation generated from JSDoc in these cases. Swagger UI won't fit in this case and updating pcs.md seems to not grasp all possible details of the interface as we would have on a generated doc.

I'm curious about what @mobrovac and @Pchelolo think about that, are there other options used by the WMF regarding js libraries documentation?

I'm curious about what @mobrovac and @Pchelolo think about that, are there other options used by the WMF regarding js libraries documentation?

Adding @apaskulin as a domain expert, since I'm definitely not one. I guess our frontend teams have some experience with publishing jsdoc...

Related T187672: Release jsdoc-wmf-theme 1.0 (Wikimedia theme for JSDoc3).

Let's use the JSDoc format and the tooling/theme for publishing can happen separately.

@Jdlrobson @Niedzielski Can you guys comment on how you are jsdoc'ing these days? Thanks!

We should also update the markdown tutorial/docs on page library pagelib/docs/pcs/pcs.md.

We should also update the markdown tutorial/docs on page library.

My intent was that the new documentation generated by this process would replace that, but if it remains around it would need to be kept up-to-date as well

Can you guys comment on how you are jsdoc'ing these days?

I don't think much has changed for us. I'm hoping that we can start using JSDocs for type checking very soon in T239262 similar to https://github.com/joakin/check-js-with-ts and we're trying to publish docs to doc.wikimedia.org (e.g., T239258).

Change 562521 had a related patch set uploaded (by MSantos; owner: MSantos):
[mediawiki/services/mobileapps@master] hygiene: remove pcs unused code

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

Change 562521 merged by jenkins-bot:
[mediawiki/services/mobileapps@master] hygiene: remove pcs unused code

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

Change 566806 had a related patch set uploaded (by Joewalsh; owner: Joewalsh):
[mediawiki/services/mobileapps@master] Adjust the PCS client interface for consistency - Ensure title is passed for read more links - Remove event logging query param from footer links - Remove 'clicked' references (not many mobile users have a mouse) - Add comment about client dependency on enum values

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

Change 566806 merged by jenkins-bot:
[mediawiki/services/mobileapps@master] Adjust the PCS client interface for consistency - Ensure title is passed for read more links - Remove event logging query param from footer links - Remove 'clicked' references (not many mobile users have a mouse) - Add comment about client dependency on enum values

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

Change 566832 had a related patch set uploaded (by Joewalsh; owner: Joewalsh):
[mediawiki/services/mobileapps@master] Fix interaction with footer read more items, ensure the the a tag is used

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

Change 566832 merged by jenkins-bot:
[mediawiki/services/mobileapps@master] Fix interaction with footer read more items, ensure the the a tag is used Use a string enum to simplify interaction with the client

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

LGoto lowered the priority of this task from High to Medium.Apr 8 2020, 3:37 PM
LGoto lowered the priority of this task from Medium to Low.
JoeWalsh claimed this task.