Page MenuHomePhabricator

Create Wikimedia theme for JSDoc3 (version 1)
Open, LowPublic

Description

None of the themes that are currently available for JSDoc support all the features we need. We'll probably have to make our own. @cscott has already created jsdoc-wmf-theme that borrows its look from the style guide.

Potential requirements

  • Allow developers to group logically related classes. For example with categories, or a custom table of contents.
  • When viewing a class, must show the full interface of a class including inherited methods.
  • Ability to show only public methods (e.g. hide private/protected). Either by default, or with a way to toggle: https://gerrit.wikimedia.org/r/c/jsdoc/wmf-theme/+/447970
  • Basic search for a method by name (e.g. searching "doFoo" will find "Quux.doFoo").
  • Ability to show/hide method & member summaries
  • Complete and compact display of the class hierarchy

Event Timeline

Volker_E renamed this task from Create a theme for JSDoc3 to Create a “Wikimedia” theme for JSDoc3.Feb 20 2018, 5:43 PM

I've started on this! https://github.com/cscott/jsdoc-wmf-theme

Most of my work to date has actually been making the link syntax a bit more robust, making it easier to link to other modules without always using the verbose 'longname' syntax. I've also added autolinking of things which look like URLs and phab tickets.

To the "requirements" list I'd add "ability to show/hide method & member summaries" as well, since it's hard to get a good idea of what a given class does if you have to scroll through pages and pages of docs on every single method.

Yep, I've included a link to the github repo in the task description too.

Most of my work to date has actually been making the link syntax a bit more robust, making it easier to link to other modules without always using the verbose 'longname' syntax. I've also added autolinking of things which look like URLs and phab tickets.

Awesome

From a short conv with @Krinkle, we should make sure that we're providing additional value over only going through code. Some of the examples additionally to the ones above:
Must-haves

  • Hierarchy

image.png (437×265 px, 43 KB)

  • Events

image.png (129×1 px, 17 KB)

Nice-to-haves

  • chainable methods flag

image.png (127×411 px, 23 KB)

Nice-to-haves, but prob not feasible:

  • Code editor and connected Live preview

image.png (170×455 px, 21 KB)

Thanks Volker for separating out the content types. I will get on it :) much easier to do this now

Thanks, that's helpful. is there a way I can see the progress of applying our style to jsdocs? i saw a link on github that was broken

And complete and compact display of the class hierarchy is the most important thing here from my perspective – that's pretty much the only thing I use the generated docs for, since I can find everything else directly in the source code editor that I already have open ;)

  • Events

I don't think I follow, don't we already have this? For example, in http://ooui-wmf.surge.sh/OO.ui.ComboBoxInputWidget.html?

Krinkle updated the task description. (Show Details)

I've made the requirements more explicit, and in some cases loosened them a bit to make it easier to get us toward JSDoc.

Specifically:

  • "Search": Basic search for a method by name (e.g. searching "doFoo" will find "Quux.doFoo"). This means indexing of descriptions, parameters, or partial word matches, or case-insensitive matching are nice-to-have but not blocking MVP (e.g. whereby "foo" would find "Quux.doFoo").
  • "Hiding visibility: inherited": I don't think it's required to be able to toggle inherited methods. It's only important that they can be seen. JSDuck showed them by default, with an option to hide them. I think the hiding isn't a blocker if, e.g. they are shown by default.
  • "Hiding visibility: private": Same, by opposite. It's important that we can view classes with just the public methods shown. If for some reason, it doesn't have a toggle, or if we can work around it by not indexing private methods, that would be fine as starting point.
  • Events

I don't think I follow, don't we already have this? For example, in http://ooui-wmf.surge.sh/OO.ui.ComboBoxInputWidget.html?

When Volker and I were looking at this there were a couple of very major bugs. I don't recall them specifically, except for one, which is that the sidebar dumps all event names in the codebase without context, which is unusable given the many apparent duplicates:

Screen Shot 2018-05-01 at 00.45.38.png (1×614 px, 72 KB)

I'd say we probably don't need this section in the sidebar. Events are quite scoped to individual classes. There would not be a need to look up an event by name globally from the home page, just as much as one wouldn't have a view of all property names or method names from all classes combined.

Requirement: Ability to show/hide method & member summaries.

I'm not sure this should be a requirement. JSDuck didn't have it either, and personally I would sections expanded by default without toggle, over hidden with ability to expand (if having to choose).

I suspect the decision to make the sections collapsible may've come from the need for a birds-eye view, given there is no table of contents. But, currently it isn't serving this purpose well, because the headings and margins are too big to be scannable. Even when collapsed, it's a long page with almost no information in view while scrolling.

Looking at JSDuck, I just realised it also collapses descriptions by default. Yet, JSDuck's view never felt to me like it hid information. It does a few things to accomplish this:

  • In collapsed form, methods still show the first line of their description, and their signature, return value, inheritance source, visibility (protected/private), and chain-ability.
  • The vertically compact form makes good use of screen estate while still leaving plenty of "air".
  • There is a tables of contents, and its always available from the sticky header.
  • There is a way to filter the current members in view (from the class-local search bar).
  • Global search.
  • Auto-expanding the target section when linking from any of the above.

Of these, I think only the description preview is important for an MVP:

  1. The description helps users decide what method to use in their code, and thus expand. Without this, they may have to expand many sections before finding what they're looking for.
  2. The documentation is meant to provide added value over looking at code on GitHub or Gitiles directly. There, descriptions are always shown and are scannable at once through scrolling.

Unlike sections in a Wikipedia article where sections (usually) communicate well what they contain, a user looking to use an API may not know which method to use. Those descriptions are important for that (perhaps more comparable to how Page Previews help decide what link to click, instead of comparing to article sections). Developers actually optimise for this. It's conventional for method descriptions to start with a one-line summary and then describe the rest in new-line separated paragraphs after that. Again, comparable to text extracts in Page Previews.

Screen Shot 2018-05-01 at 01.00.01.png (1×2 px, 227 KB)
7 methods (with signatures and return types).
Screen Shot 2018-05-01 at 01.01.38.png (1×2 px, 713 KB)
Contextual header (sticky), table of contents, search, and 10 methods (with signatures, return types, and summaries)

The contextual header is also important given that without it, there is no visible way within the web page to identify what class is being viewed. The browser might show the class name in the url or tab name, but nowadays browsers quite often reduce visibility of address bars and/or tabs to just an icon or domain name.

A few screenshots from JSDuck for context:

Table of contentsCollapsed viewExpanded view
Screen_Shot_2018-05-01_at_00.51.34.png (1×2 px, 845 KB)
Screen Shot 2018-05-01 at 00.51.52.png (1×2 px, 608 KB)
Screen Shot 2018-05-01 at 00.52.10.png (1×2 px, 618 KB)
Volker_E moved this task from Inbox to Backlog on the Front-end-Standards-Group board.

Putting this to Backlog as Design has other priorities to fulfil until at least end-of-quarter.

And complete and compact display of the class hierarchy is the most important thing here from my perspective – that's pretty much the only thing I use the generated docs for, since I can find everything else directly in the source code editor that I already have open ;)

I am working on a JSDoc plugin that puts this data in the TaffyDB, and adds the list to the class description in a makeshift manner (no links). Do we want to show all subclasses too? I am thinking that the rendering should be the theme's responsibility (working on that), but, we could have a plugin config that shows something without styling, like below:

Screen Shot 2018-07-04 at 12.09.05 PM.png (790×1 px, 152 KB)
Screen Shot 2018-07-04 at 12.49.23 PM.png (1×1 px, 216 KB)

I'd say we probably don't need this section in the sidebar. Events are quite scoped to individual classes. There would not be a need to look up an event by name globally from the home page, just as much as one wouldn't have a view of all property names or method names from all classes combined.

Add hideSections config — https://github.com/cscott/jsdoc-wmf-theme/pull/2

Unlike sections in a Wikipedia article where sections (usually) communicate well what they contain, a user looking to use an API may not know which method to use. Those descriptions are important for that (perhaps more comparable to how Page Previews help decide what link to click, instead of comparing to article sections). Developers actually optimise for this. It's conventional for method descriptions to start with a one-line summary and then describe the rest in new-line separated paragraphs after that. Again, comparable to text extracts in Page Previews.

Apparently JSDoc has a @summary tag for exactly this. I feel adding these will make the documentation too verbose, what do you think?

We could use the first line of the description if there is no summary present - https://github.com/cscott/jsdoc-wmf-theme/pull/4

Screen Shot 2018-05-01 at 01.00.01.png (1×2 px, 227 KB)
7 methods (with signatures and return types).
Screen Shot 2018-05-01 at 01.01.38.png (1×2 px, 713 KB)
Contextual header (sticky), table of contents, search, and 10 methods (with signatures, return types, and summaries)

Trying out a sticky header, sticky ToC and changed margins on the current design

Screen Shot 2018-07-11 at 12.10.23 PM.png (1×2 px, 310 KB)
Header with class name, search, ToC, 9 methods (with signatures, return types, and summaries)

I have never really used the list of methods/events from the sticky header. Is this something we'd want to add to the new theme?

I am working on a JSDoc plugin that puts this data in the TaffyDB, and adds the list to the class description…

https://www.npmjs.com/package/jsdoc-class-hierarchy

From the description:
  • Ability to show only public methods (e.g. hide private/protected). Either by default, or with a way to toggle.

https://github.com/cscott/jsdoc-wmf-theme/pull/7

From the description
  • Basic search for a method by name (e.g. searching "doFoo" will find "Quux.doFoo").

https://github.com/cscott/jsdoc-wmf-theme/pull/8

Change 447970 had a related patch set uploaded (by Prtksxna; owner: Prtksxna):
[jsdoc/wmf-theme@master] Add method toggle filter

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

Change 447969 had a related patch set uploaded (by Prtksxna; owner: Prtksxna):
[jsdoc/wmf-theme@master] Add lunr search

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

Change 447969 merged by C. Scott Ananian:
[jsdoc/wmf-theme@master] Add lunr search

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

Change 460075 had a related patch set uploaded (by Niedzielski; owner: Stephen Niedzielski):
[mediawiki/extensions/MobileFrontend@master] WIP: add WMF theme to JSDocs

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

Change 447970 merged by C. Scott Ananian:
[jsdoc/wmf-theme@master] Add method toggle filter

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

This covers everything mentioned in @Krinkle's comment. I have also updated the oojs/core patch to use the new theme and plugin.

The only thing that wasn't on that list, and is still remaining is the customisable table of contents. I too think we can go ahead without it, at least for oojs core.

@Prtksxna Wow, very nice!

Good stuff

I saw some good stuff I'd like to highlight:

  • Search: » Looks great. Works great.
  • Class hierarchy and child classes: » Nice.
  • Class tag "abstract": » Great.
  • Visibility filters: » Looks good.
Major bugs

I also noticed a couple of bugs of which two bugs (I think) should be blocking, The rest can be addressed in later iterations, as we adopt this further.

  1. Private members are missing.   The UI for visibility filters exist, and protected members are visible and toggle-able (e.g. EventList#insertItem), but while a toggle exists, it appears to not work (e.g. EventList#moveItem is missing). For comparison, they do appear at https://doc.wikimedia.org/oojs/master/#!/api/OO.EmitterList.
  1. Most of the UI elements are inaccessible.    I've had to perform most UX tests with the keyboard instead of the mouse due to this bug. Something to do with the negative-margin trick used for the headings. This also affected the visibility filter checkboxes, and the return type anchor links.
capture-1.png (1×1 px, 255 KB)
capture-2.png (1×2 px, 348 KB)
Minor bugs

(in no particular order)

  1. The "Mixed" return type looks like and behaves like a link, but does nothing when clicked. Should presumably be plain text instead.
  1. Each page has three page titles. I think having more than one is useful (one static in text, one in sticky nav-bar). But I think, three is confusing. They should also have more consistent formatting. Currently, tab title is "JSDoc: Class: EventEmitter", sticky header is "OOjs: Class: EventEmitter", first heading is "Class: EventEmitter", and second heading is "OO.EventEmitter". I don't particularly mind how we solve this, but here's a few things I'd consider:
    • The documented entity should be consistently referred to. Not as both "OO.EventEmitter" and "Class: EventEmitter". I think the correct one here is "OO.EventEmitter". The "Class" prefix is useful for the nav bar as a form of breadcrumbs, but perhaps not in the heading?
    • Either the first and second heading is redundant. Might want to remove one of them, or make each of them useful in their own way.
    • For tabs, it might be better to inverse the path so that the main entity is at the front (given limited size of the browser tab). E.g. "OO.EventEmitter - Classes - OOjs".
    • For the nav heading, I think the intention of providing a full path of "where am I" is very useful. However, the current phrasing sounds too much like a single title instead of a path. Instead of "OOjs: Class: EventEmitter", perhaps "OOjs / Classes / OO.EventEmitter" would work better.
      capture-3.png (948×1 px, 82 KB)
  1. The class properties are missing from sub/mixin targets. For example, OO.EventEmitter#bindings is documented in the code and present on the EventEmitter output, but missing from the OO.Factory and OO.Registry classes. (jsduck)
  1. Unclear relation between method names and descriptions. There is currently no spacing between sections. This is a problem because it's visually ambiguous which heading a description belongs to. The styling applied here (presumably inspired by Minerva) made sense before in the earlier mockups when we didn't have the descriptions yet. It was just headings (like on Wikipedia). Now that the first line is always shown, it probably needs some form of visual aid to identify which two belong together.
  1. Alignment of method names vs visibility indicators. When interacting with the page and searching and jumping between methods, I found myself getting confused multiple times by the visibility indicator in front of the method name. Some form of visual aid and alignment would help here, I think. The JSDuck equivalent did a lot here. It separated the indicator from the heading by encapsulating the indicator in a bubble, it also used a different text style (all-caps), text size (smaller), and colour (purple/orange vs blue). Doing all of these is probably overkill, but we may need one or two of these compared to now. Perhaps move the indicator to after the signature, and perhaps right-aligned and/or using a third color (in addition to grey and blue), or a different wrapping (e.g. square brackets). I expect you'll have better ideas here :)

Thank you for taking a thorough look at this @Krinkle

  1. Private members are missing.   The UI for visibility filters exist, and protected members are visible and toggle-able (e.g. EventList#insertItem), but while a toggle exists, it appears to not work (e.g. EventList#moveItem is missing). For comparison, they do appear at https://doc.wikimedia.org/oojs/master/#!/api/OO.EmitterList.

jsdoc doesn't include private functions by default and I forgot to add the config to show them. This is fixed in the latest patchset.

  1. Most of the UI elements are inaccessible.    I've had to perform most UX tests with the keyboard instead of the mouse due to this bug. Something to do with the negative-margin trick used for the headings. This also affected the visibility filter checkboxes, and the return type anchor links.

Ouch! I wonder how I didn't notice this (possibly because of the order of patches I was testing). Here is a very hacky quick fix - https://gerrit.wikimedia.org/r/c/jsdoc/wmf-theme/+/465930. Review and ideas are welcome.


I am going to slowly move all the other issues you mentioned to the JSDoc WMF theme project (that Sam created for me) and offer most of them for GCI. If there is anything else that is blocking jsdoc usage I'll try to get it it sooner.

Patches still awaiting review:

Setup instructions at: https://phabricator.wikimedia.org/project/profile/3689/

I am going to slowly move all the other issues you mentioned to the JSDoc WMF theme project (that Sam created for me) and offer most of them for GCI. If there is anything else that is blocking jsdoc usage I'll try to get it it sooner.

This is done.

Setup instructions are resulting in errors, filed at T209523

Change 465930 had a related patch set uploaded (by Krinkle; owner: Prtksxna):
[jsdoc/wmf-theme@master] Fix locked UI above headings

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

Change 482755 had a related patch set uploaded (by Krinkle; owner: Krinkle):
[integration/config@master] Add Jenkins jobs for jsdoc/wmf-theme (npm-test; Node 10)

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

@Prtksxna @Volker_E It seems the jsdoc/wmf-theme repo doesn't have Jenkins set up yet, and when I tried npm install-test locally it failed due jsdoc not being a devDependency and various eslint errors. Let me know if/when you want to enable the npm-test job for Verified scores on Gerrit.


PS: See T210349.

Change 465930 merged by VolkerE:
[jsdoc/wmf-theme@master] Fix locked UI above headings

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

Change 482755 merged by Krinkle:
[integration/config@master] Create generic npm-test job for Node 10 (and use for jsdoc/wmf-theme)

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

Krinkle renamed this task from Create a “Wikimedia” theme for JSDoc3 to Create Wikimedia theme for JSDoc3 (version 1).Jan 17 2019, 9:29 PM
Krinkle moved this task from Backlog to Accepted on the JSDoc WMF theme board.
Krinkle moved this task from Accepted to Backlog on the JSDoc WMF theme board.

Thank you for taking a thorough look at this @Krinkle

  1. Private members are missing.   The UI for visibility filters exist, and protected members are visible and toggle-able (e.g. EventList#insertItem), but while a toggle exists, it appears to not work (e.g. EventList#moveItem is missing). For comparison, they do appear at https://doc.wikimedia.org/oojs/master/#!/api/OO.EmitterList.

jsdoc doesn't include private functions by default and I forgot to add the config to show them. This is fixed in the latest patchset.

I've checked this out locally and generated the output, but I am still unable to make private methods visible. There is a checkbox for it, but toggling it does not make the methods appear. For example, on OO.EventEmitter, showing private should show addBinding and validateMethod.

Change 460075 abandoned by Niedzielski:
WIP: add WMF theme to JSDocs

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