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.

In T187672#4079635, @Prtksxna wrote:

In T187672#4029304, @Volker_E wrote:

• 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:

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.

	7 methods (with signatures and return types).

	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 contents	Collapsed view	Expanded view

In T187672#4051079, @matmarex wrote:

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:

In T187672#4169980, @Krinkle wrote:

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

In T187672#4170056, @Krinkle wrote:

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

In T187672#4170056, @Krinkle wrote:

	7 methods (with signatures and return types).

	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

	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?

In T187672#4396790, @Prtksxna wrote:

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

I have updated https://gerrit.wikimedia.org/r/c/oojs/core/+/405544 to use the latest version of the theme.

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.

2. 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.

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.

2. 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.
     

3. 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)

4. 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.

5. 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.

2. 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:

• https://gerrit.wikimedia.org/r/c/jsdoc/wmf-theme/+/465930
• https://gerrit.wikimedia.org/r/c/oojs/core/+/405544

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

In T187672#4657437, @Prtksxna wrote:

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.

SGTM

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

In T187672#4657437, @Prtksxna wrote:

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

Change 949595 had a related patch set uploaded (by Krinkle; author: TheDJ):

[jsdoc/wmf-theme@master] Some minor search improvements

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

Change 949595 merged by jenkins-bot:

[jsdoc/wmf-theme@master] Some minor search improvements

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

Change 951983 had a related patch set uploaded (by TheDJ; author: TheDJ):

[jsdoc/wmf-theme@master] Make properties tables of objects look like wikitables

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

Change 951985 had a related patch set uploaded (by TheDJ; author: TheDJ):

[jsdoc/wmf-theme@master] Remove unnecessary heading margins

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

Change 951991 had a related patch set uploaded (by TheDJ; author: TheDJ):

[jsdoc/wmf-theme@master] Remove ... when summary is missing

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

Change 951991 merged by jenkins-bot:

[jsdoc/wmf-theme@master] Remove ... when summary is missing

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

Change 951983 merged by jenkins-bot:

[jsdoc/wmf-theme@master] Make properties tables of objects look like wikitables

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

Change 951985 merged by jenkins-bot:

[jsdoc/wmf-theme@master] Remove unnecessary heading margins

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

Change 980971 had a related patch set uploaded (by Alex Paskulin; author: Alex Paskulin):

[jsdoc/wmf-theme@master] ui: Change Members subheading to Properties

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

Change 980971 merged by jenkins-bot:

[jsdoc/wmf-theme@master] ui: Change Members subheading to Properties

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

Change #1020264 had a related patch set uploaded (by Alex Paskulin; author: Alex Paskulin):

[jsdoc/wmf-theme@master] Release 1.0.0

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

Change #1020264 merged by jenkins-bot:

[jsdoc/wmf-theme@master] Release 1.0.0

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

Change #1023097 had a related patch set uploaded (by Majavah; author: Majavah):

[labs/libraryupgrader/config@master] releases: Bump jsdoc-wmf-theme

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

Change #1023097 merged by jenkins-bot:

[labs/libraryupgrader/config@master] releases: Bump jsdoc-wmf-theme

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