JSRef doesn't work well with certain language features

[wbamberg]

Background

{{JSRef}} is the macro we use to generate a sidebar for JS global objects and their members, like https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array and https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then.

(For other bits of JS, including the guide pages, high-level pages, and things like statements or operators, we use
{{JsSidebar}}, a different macro that generates a different sidebar, as in https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of .)

Problem

JSRef assumes that the thing it's a sidebar for is living directly underneath /Web/JavaScript/Reference/Global_Objects, and that its properties, methods, and constructor live directly underneath it. For example:

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice

This assumption breaks down for JS objects that live in a kind of namespace, like Intl, WebAssembly, and now Temporal.

These have a three-level hirarchy, with the namespace (currently) under /Web/JavaScript/Reference/Global_Objects, then static members and the objects in that namespace under that, then members of those objects at a third level:

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory/grow

...and JSRef isn't really able to represent this at all.

Current workaround

We work around this by manually adding the objects to the "related pages" item for that namespace, but it's far from ideal.

Solution

Fixing this would take some careful thought about how we want to represent these things. Sidebar design is tricky. Perhaps we don't want to have them under "Global_Objects" at all? It seems a bit of a stretch to call Intl an object when you can't instantiate it. Should we have "Namespaces" at the same level as "Global_Objects"?

In general I do think it would be worth using this as an opportunity to revisit the JS sidebars as a whole. There are a few other things we might consider:

• sidebars created using JSRef show inheritance (usually Object and often Function) and list all inherited members of the objects they inherit from. It's been suggested that these aren't very useful.
• we have discussed in the past having a single sidebar for all of JS, as we now have for CSS. This will make the sidebar massive though, so having scrollable sidebars might be a prerequisite.

Note that we talked about a new JS sidebar a lot in the old stumptown work, and some of that might be reusable here: mdn/stumptown-content#302 (comment).

[caugner]

@wbamberg What is your opinion on this nowadays?

1. Would you want to stick with two separate sidebars (JSRef + JSSidebar) or merge them?
2. What next steps would you suggest (ideally highlighting the more important ones)?

[wbamberg]

This issue was mostly prompted by things like Intl that aren't at all well served in the current sidebar design (see for example https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/supportedLocalesOf, where I don't get to see any of the members of Collator). So one more limited option would be just to address them, in the context of the current sidebar design.

Another is (as the issue says) to make much bigger changes to the JS sidebar. I like having a single sidebar for a domain if possible, because it gives a much more consistent experience when navigating around. We now have single sidebars for CSS and for HTML (since #7402 ). Now we have auto-scrolling sidebars I think these kinds of sidebars work better, although we could certainly improve the CSS one with some design work.

I also expect that @Josh-Cena has views on this though so we should ask him.

[Josh-Cena]

Jumping in, but I really don't have great ideas about the sidebars work.

1. I do favor "sub-sidebars" in general. For example, I wish "errors", "operators", "statements", and "global objects" all have their respective sidebars, instead of being cluttered as dropdowns—it's really hard to scroll. If possible, I also wish the sidebar has richer typography, instead of just a few <details>, but I don't have great suggestions.

• sidebars created using JSRef show inheritance (usually Object and often Function) and list all inherited members of the objects they inherit from. It's been suggested that these aren't very useful.

Strongly agree. See also: mdn/content#20019. Objects that have actual inheritance are not displayed as such at all: typed arrays, errors, etc.

3. Indeed, the sidebars for Intl is terrible. My idea is to treat Intl.NumberFormat as if it's a top-level object, and only show Intl, Intl.supportedValuesOf, etc. when you are actually on the Intl root page.