Talk:JSDoc WMF theme

Bunch of stuff missing from MediaWiki core JavaScript docs

Visiting https://doc.wikimedia.org/mediawiki-core/master/js/index.html doesn't show much. I was hoping to find documentation on mw.loader.using, but it is not in the list. Anything we can do to fix? –Novem Linguae (talk) 13:03, 29 November 2023 (UTC)

Hey thanks for the prompt and thanks for letting us know what you need! I've created a ticket for tracking this work (https://phabricator.wikimedia.org/T352308) I'll make sure that loader gets prioritized next. Jdlrobson (talk) 15:51, 29 November 2023 (UTC)

Thanks for the ticket. I went ahead and subscribed. Any reason that you don't just include everything though? I imagine these files have docblocks and that the docblocks are accurate. It isn't as simple as letting jsdoc generate everything? –Novem Linguae (talk) 11:03, 30 November 2023 (UTC)

Hmm. Looking at gerrit:978717, I guess the problem is jsduck and jsdoc have slightly different keywords, and these need to be changed by a human? Stuff like member->memberof? –Novem Linguae (talk) 11:06, 30 November 2023 (UTC)

For now, I'm doing this manually as it's a chance to review the existing documentation on a small subset of the library and work out what's useful, what's not and where the documentation can be improved e.g. with examples.

Once we get some more confidence about the porting process and what we want to map to I think we could automate the rest of it.

For example a lot of the existing documentation is using @class on things that are not classes.

Here's a snapshot of code I'm currently porting:

https://jdlrobson.github.io/jsdoc/index.html

As someone who uses the documentation, I'd be curious if you have any thoughts on how it's evolving and what feels weird... Jdlrobson (talk) 03:27, 1 December 2023 (UTC)

Your snapshot looks much more complete than what's currently up. Hopefully we can get that merged soon :) –Novem Linguae (talk) 20:21, 6 December 2023 (UTC)

Make theme more like desktop?

Currently the theme looks a lot more like Minerva instead of V22, which is quite jarring when I navigate to it. Also, is there some sort of way there could be quick button navigation to the different types of members like JSDuck did? Maybe yet another TOC?
Additionally, currently every single short description reads "...". Is this a known issue while the docs are ported? Aaron Liu (talk) 23:24, 29 November 2023 (UTC)

Thanks for this feedback! Can you say more about "navigation to the different types of members"? Is there a similar feature in the JSDuck docs?

I see what you mean about the short descriptions. It looks like the summarize plugin needs to be enabled to display previews of the descriptions. I've opened phab:T352494 for that fix. APaskulin (WMF) (talk) 22:23, 30 November 2023 (UTC)

Yes. Right under the object name there's a bar with the name of every section, such as "Configs 34 Properties 4 Methods 67 Events 5". You can conveniently click on them to jump to the section. Aaron Liu (talk) 01:06, 1 December 2023 (UTC)

I see. Those quick links are really helpful. I've added a comment with that idea on phab:T344897. --APaskulin (WMF) (talk) 22:40, 5 March 2024 (UTC)

Should private methods be documented

By default jsdoc does not include methods marked as @private in the output. This is helpful as it can be used to describe functions that meet the Stable_interface_policy/Frontend and it reduces the clutter of the documentation surfacing the useful stable functions gadget developers use every day.

What do people think about this?

Including @private seems to be as simple as adding an argument to the documentation generation command, so we could also explore multiple versions for multiple audiences if there was appetite for that.

Curious on everyone's thoughts... Jdlrobson (talk) 03:29, 1 December 2023 (UTC)

I think private functions should be included, but not shown by default. Knowing about private functions helps when you get weird behaviour and need to know about internals. Nux (talk) 21:27, 1 December 2023 (UTC)

Having thought about it maybe I only really need this in ExtJS, because sometimes I override their classes and seeing private/protected things helps to avoid clashes and debug when clashes occur... So I guess that would depend on how would Codex work (do you need to inherit from other components more, how inheritance works). Haven't had the chance to test them. Nux (talk) 21:52, 1 December 2023 (UTC)

FWIW, inheritance is not really a thing in Codex—we follow a pattern of composition instead. Building a component for a feature will mean either using a single Codex component's props and slots to build a customized instance of that component, or using Codex components as building blocks to create an entirely new component. Additionally, Codex's documentation is generated via different tools so it won't be covered in the mw core documentation. ATomasevich (WMF) (talk) 15:28, 4 December 2023 (UTC)

In that case I vote for not including private methods 🙂. At least from a gadget author perspective. Nux (talk) 18:43, 4 December 2023 (UTC)

I used the JSDuck docs to explore MediaWiki architecture and for MediaWiki core programming sometimes. And it probably gets search engine indexed for easier googling. So I do think there's a use case for showing private stuff. –Novem Linguae (talk) 20:20, 6 December 2023 (UTC)

What was the php and js status quo before the migration? Did either set of docs show private methods? –Novem Linguae (talk) 22:43, 8 December 2023 (UTC)

@Novem Linguae ExtJS always shown private methods (using that in daily job). JSDuck is from ExtJS (from older ExtJS, maybe v3 or v4). For reference: new ExtJS docs (grid). On the left you only see classes and on top left you have menus with props, methods etc. which are filtered with the top-right checkboxes. So much like in JSDuck e.g.: OO.ui.Element (note that checkboxes are hidden in "Show" menu).

BTW. Personally I don't use those menus often (props, methods etc). Most of the time I just filter members. Menus are mostly useful for me to see how many methods where matched by filters. So showing numbers beside checkboxes would be useful for me. Nux (talk) 23:29, 8 December 2023 (UTC)

Changed my mind. Maybe just putting public methods in the docs for both PHP and JS would make the most sense. If I'm using the docs, that probably means I'm not changing code in the class itself, because then I'd just look up the methods in the method list in my code editor. –Novem Linguae (talk) 22:44, 10 December 2023 (UTC)

As they say, "WMF devs created API methods; the inability of JavaScript to natively restrict access to private methods made them equal". As for someone who likes to dive deep into the inner workings of the API, that would be useful for me. Too bad you can't turn them on/off like in JSDuck. JWBTH (talk) 01:02, 1 February 2024 (UTC)

Side note: many languages have ways to access private methods (e.g. for testing, ORM etc). Private/protected is just a contract. You should generally respect the contract, even if it is only enforced by @private ;). Nux (talk) 02:03, 1 February 2024 (UTC)

Add some icons or other type indicators

I noticed problems when navigating over namespaces. When I click on `window`, `mw.util` i get a page with a header. Then I click on `mw.log` and I don't know what happened - `mw.log` is not selected and the page looks different. It would help if there would be some other level or some icon to indicate I'm navigating to something different.

BTW. I think adding `scroll-padding-top:` (CSS) would help in making navigation feel more connected. When you navigate source code [1] the highlighted line is not visible. Same thing when you click on mw.log (it works initially, but when you click again it shows something different). Same problem with search (when run twice). CSS will probably fix all problems like that.

And BTW maybe also highlight the function when e.g. mw.log is clicked/selected (from navi and search). Nux (talk) 21:45, 1 December 2023 (UTC)

Thanks for this feedback! I think these problems are fixed now. The current page should be highlighted in the navigation sidebar and scroll-padding-top has been fixed. Let me know if you run into these issues again. --APaskulin (WMF) (talk) 22:40, 5 March 2024 (UTC)

Some random thoughts

• It’s great that standard objects link to MDN instead of duplicating the documentation for some (e.g. String) while leaving others unlinked (like HTMLElement).
• I like that it looks like something that’s part of the MediaWiki/WMF world, not a totally foreign piece of software.
• I don’t like the much blank space, especially as it’s at the expense of losing some features:
  • Tabs (although I could probably get used to using browser tabs instead)
  • Table of contents for the current object (Properties, Methods and Events, with dropdown menus to select the property/method/event I’m interested in)
  • Filter for the current object
• The much blank space, somewhat surprisingly, is more crowded for me than less blank space would be.
• The JSDuck interface uses pills for static, protected etc. (not the documentation of mw.util, though, but see e.g. OO.ui.Element.getBorders()), which for the first look seemed easier to recognize. For the second look, I’m no longer sure…
• The _opt subscripts are almost impossible to see (color contrast according to the Firefox toolbox is 2.37 : 1, which is far from the AA-level 4.5 : 1, let alone AAA-level 7 : 1). In addition to the unnoticeable color, the bracket notation (used in the JSDuck tool) is widespread and easier to understand. Could we get that back?
• Is it necessary to write Array.<string> instead of string[]? The latter is shorter and quite standard (used by C, Java, PHPDoc etc.). Even the source code itself uses that.
• Why are nulls wrapped in extra <code> elements? HTMLElement is also to be taken literally, yet it doesn’t get the extra wrapping.
• The return type of parseImageUrl in the collapsed form (after the →) is totally off, it doesn’t seem to be able to handle when object members are documented. The uncollapsed part isn’t great either, but at least not a lie.
• The source code browser has strange gray horizontal lines between each two source code lines, which make the code much harder to read. Is it just me (Firefox 115.5.0esr)?

Tacsipacsi (talk) 23:18, 1 December 2023 (UTC)

I'm keeping track of a list of issues as well, which can be found here https://phabricator.wikimedia.org/T138401#9079509. Many of your issues are also on my list of gripes. —TheDJ (Not WMF) (talk • contribs) 09:09, 7 December 2023 (UTC)

Thanks for this feedback!

• HTMLElement now links to MDN as well. I've opened phab:T359218 to add the remaining missing links that were included in JSDuck.
• The information density is definitely lower compared with JSDuck. The theme was based on the Wikimedia design style guide, which wasn't designed for this type of information. Ideas to increase the information density are welcome.
• See phab:T344897 for ideas about how to improve navigation within the page.
• There are now pills for static, protected, etc.
• Great points about the _opt subscripts. I've opened phab:T359222 to fix this.
• According to the JSDoc docs, it seems that string[] is supported.
• I'm not sure why null gets extra code styling. Can you link to an example of HTMLElement used literally? I'm only seeing it as a type (example).
• The ResizeableThumbnailUrl type looks correct to me now. Can you confirm whether this is still appearing incorrectly?
• I agree with your point about the source code files. I've opened phab:T359223 to fix this.

--APaskulin (WMF) (talk) 22:40, 5 March 2024 (UTC)

Move this to a sub-page of the main JSDoc docs?

What do people feel about moving this to JSDoc or similar? Jdforrester (WMF) (talk) 14:12, 4 December 2023 (UTC)

This feels more like a project/workstream page to me e.g. like Desktop Improvements but I defer to Alex around moving it.

I do think a JSDoc page for documenting how we use it would be useful regardless. Jdlrobson (talk) 23:01, 4 December 2023 (UTC)

I'd prefer to keep a flat structure with these two pages since I don't expect to need more pages related to this topic. APaskulin (WMF) (talk) 22:30, 19 December 2023 (UTC)

@APaskulin (WMF) OK. It feels a bit marooned here to me, but I'll defer to you. :-) Jdforrester (WMF) (talk) 11:17, 2 January 2024 (UTC)

Syntaxhighlighting

The snippets (e.g. those can be found here) are displayed as plain text with no highlighting. Is this expected? NguoiDungKhongDinhDanh (talk) 12:22, 29 December 2023 (UTC)

Its a bug in the current version of the theme release. The next release already has it fixed. —TheDJ (Not WMF) (talk • contribs) 13:04, 29 December 2023 (UTC)

Update and request for feedback

Hi everyone, A huge thank you to everyone who has provided feedback so far, both here and on the theme workboard! At this point, we've migrated almost all the files in MediaWiki core, updated the homepage to help guide new developers, and made several improvements to the theme.

As we review the last few patches, complete a final review of the docs, and work towards the v1.0 release of the theme, we'd like to ask for your feedback again:

• What's missing from the documentation that's important to you?
• What issues do you notice with the existing documentation?
• How can we improve the documentation?

APaskulin (WMF) (talk) 18:06, 8 March 2024 (UTC)

Honestly, it's hard to see it's an improvement purely from a reader's point of view. In JSDuck everything was organized according to the access point from the global scope so you knew where to look for. Now they're hidden in different sections, which not only increases the interaction cost but makes which page belongs to which section seem really arbitrary (especially given some classes like mw.Title have static methods which may be more often used than the constructor). Then some links (especially in "Events") are too long to fit in the sidebar. Couldn't you restore the tree-like structure? Failing that, merge "Classes" and "Namespaces" and allow text wrapping in each item in the sidebar? Nardog (talk) 02:25, 10 March 2024 (UTC)

Thanks for this feedback, @Nardog. We're going to try out some alternative organizations and get back to you with some ideas. APaskulin (WMF) (talk) 23:56, 15 March 2024 (UTC)

Hi all, We've put together a demo of an alternative navigation strategy for the JSDoc theme. We wanted to rely less on the sidebar, where spacing and font size limit information density, and instead use landing pages to orient readers and breadcrumbs to indicate hierarchy.

Changes:

• Replaces the Namespaces and Classes sections in the sidebar with a short list of top-level namespaces under "Frontend API" and a landing page to provide context
• Adds more prominent breadcrumbs on class pages to indicate hierarchy and provide navigation back to top-level namespaces
• Adds a landing page for the Modules section to introduce the concept of modules
• Adds a sitemap page to provide a complete list of everything on the site, which can be configured to display by section (as shown in the demo) or displayed in one, unified list (Note that this page is currently missing styles for mobile)

These changes are still a work in progress, but we wanted to share the demo and see if this approach helps reduce some of the confusion around which things belong in which section. APaskulin (WMF) (talk) 21:40, 25 March 2024 (UTC)

This does seem a lot more readable ! —TheDJ (Not WMF) (talk • contribs) 08:45, 26 March 2024 (UTC)

@APaskulin (WMF) btw. I think Vue should go into that Frontend Api list ? —TheDJ (Not WMF) (talk • contribs) 20:59, 26 March 2024 (UTC)

Great point! It would need to be a namespace to go under Frontend API, but we had talked about documenting Vue as a module instead of a class, so I've opened a patch to do that: gerrit:1015160. APaskulin (WMF) (talk) 00:13, 28 March 2024 (UTC)

Thank you for trying something out, but I'm afraid I don't particularly see it as an improvement, as the interaction cost has increased. It looks like you just hid certain things instead of improving (or restoring) them. When you're on e.g. mw.Api, couldn't the sidebar show the sibling pages, i.e. cldr, cookie, Debug, Feedback, etc., and so on? I liked with JSDuck you could grasp the whole hierarchy in a glance, and I'd like to see that again. Nardog (talk) 03:35, 29 March 2024 (UTC)

Why do you need access to mw.cookie, mw.Debug, mw.feedback from mw.Api - none of these are related APIs? In general the previous jsduck hierarchy seems misleading to me, as the only thing these libraries have in common is they are stored on a global called mediawiki.

I think hierarchies only make sense to describe inheritance models such as in the OOUI theme which makes heavy use of object orientated programming. 118.189.23.193 21:28, 1 April 2024 (UTC)

You don't want just what's related to the thing you're currently reading about. You want what's out there, what's possible.

I learned a lot by traversing the JSDuck tree and stumbling upon various APIs. I wouldn't have learned as much or as quickly had I had access only to the current JSDoc. Nardog (talk) 02:56, 28 April 2024 (UTC)