Sprints: Update DefaultAPISidebar macro for new event organisation

[wbamberg]

This is a work item for #685, and was originally discussed in https://github.com/mdn/sprints/issues/906.

The DefaultAPISidebar macro currently refers to GroupData to list events. We need to change this as part of the event refactoring wok, and instead treat events more like other subpages of the API (e.g. properties and methods).

Like APIRef, DefaultAPISidebar is complex. Although it's not as widely used as APIRef we should still add tests before making this update. So a prerequisite for changing it is adding tests.

In this user story we will:

• add tests for DefaultAPISidebar, using an adapted version of the APIRef test plan here: https://github.com/mdn/kumascript/pull/1080#issuecomment-466114220 as a guide (they are pretty similar macros)
• update DefaultAPISidebar to look for events in subpages instead of GroupData

AC are that both those changes are committed to KumaScript, deployed, and verified.

[wbamberg]

Here's how I think DefaultAPISidebar works, what it's supposed to be for, and what we'll need to change.

---

How it works

Inputs

This macro gets passed a string. This is intended to identify a "group" in the GroupData macro, like "Ambient Light Events" or "Channel Messaging API". I'm not sure what determines whether group names get the " API" suffix, that seems random.

We load GroupData and find the group, and use it to initialize some arrays:

• interfaces: the contents of group.interfaces
• methods: the contents of group.methods
• properties: the contents of group.properties
• events: the contents of group.events

We also initialize:

• guides: this is the concatenation of:
  
  
  
  • all the subpages under group.overview
  
  
  • group.guides
  
  

Outputs

We then write out:

• a link to group.overview, if that exists. This will be an overview page like https://developer.mozilla.org/en-US/docs/Web/API/Channel_Messaging_API.

• in separate subsections: the guides, interfaces, properties, methods, and events

---

What's it for?

As I understand it this sidebar is supposed to be for pages that document what we call "APIs" as opposed to "interfaces". The difference is that an "interface" is a single concrete object that a web developer might encounter, while an API is a more abstract collection of features, that may include multiple interfaces and also individual methods belonging to other interfaces. Generally it seems that APIs align with specifications.

For example. There's an API we call the Fetch API, that contains all the stuff under the abstract concept of Fetch. This includes specific objects (interfaces) like Request and Response, but also includes the fetch() method of the WindowOrWorkerGlobalScope interface.

To document this abstract thing called "Fetch", we have an overview page whose name is usually (but not always) of the form "_APIName__API". This page gives an overall description of the API. It may also have subpages, which are guides to aspects of the API.

For example: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API, which has child pages like https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Cross-global_fetch_usage.

So, the idea is that we use DefaultAPISidebar for pages like this. Then:

• group.interfaces is obvious: it lists the interfaces that comprise the API.
• "guides" includes the subpages, and the concatenated group.guides also lets you point to other guides that are not under the overview page, and it will list them too. Actually I think we should remove group.guides but that's another conversation.
• group.methods and group.properties, importantly, are specifically for methods and properties _not included under interfaces_. For example, under "Fetch API" we list WindowOrWorkerGlobalScope.fetch() but not Request.json(). I wonder how clear this distinction is to users...

---

So what about events?

So this brings us to group.events. Honestly, the way these are done at the moment appears to be a bit random, but to follow methods and properties it seems we should say: events whose target is an interface already included under group.interfaces should not be included, but events whose target is a different interface should.

For example, under the "File API" we currently have:

"File API": {
    "interfaces": [ "File",
                    "FileList",
                    "FileReader",
                    "FileReaderSync",
                    "Blob" ],
    "methods":    [],
    "properties": [],
    "events":     [ "loadstart",
                    "progress",
                    "abort",
                    "error",
                    "load",
                    "loadend" ]
}

There events all target the FileReader interface which is where they are now documented. So we should remove these events.

However, under the "Clipboard API" we have:

"Clipboard API": {
    "interfaces": [ "Clipboard",
                    "ClipboardEvent"],
    "dictionaries": [ "ClipboardPermissionDescriptor" ],
    "methods":    [],
    "properties": [ "Navigator.clipboard" ],
    "events":     [ "beforecopy",
                    "beforecut",
                    "beforepaste",
                    "clipboardchange",
                    "copy",
                    "cut",
                    "paste" ]
}

In this case these events - cut, copy and so on - target Element, so we should keep them, but list them as "Element.cut" and so on.

Then we also need to update DefaultAPISidebar so it treats events in the same way as methods and properties - currently the macro assumes that events live under Web/Events. And before that of course we have to write tests for this macro.

---

I also think there are other changes we ought to make to DefaultAPISidebar and GroupData, to make it all a bit more sensible. But that's out of scope for the event reference work.

[ExE-Boss]

What should we use as a separator for group.events located under Web/API/<interface_name>?

I feel like a . isn't the greatest choice given that events aren’t methods or properties.

[wbamberg]

What should we use as a separator for group.events located under Web/API/?

I feel like a . isn't the greatest choice given that events aren’t methods or properties.

Yes, this is a good point, thanks! Perhaps we should use "Interfacename: eventname", like the page titles? We'd then I suppose have to transform that into "Web/API/Interfacename/eventname_event" for the link target.

[wbamberg]

@chrisdavidmills , @Elchi3 , please let me know if you think the above sounds like a good approach.

[wbamberg]

GroupData updates

I've made a first pass through the events in GroupData, summarised in this sheet: https://docs.google.com/spreadsheets/d/1-G5q6sqiT6iSz-O3tJMhdDjBWazXUvXeVoyP6eWH4X0/edit#gid=0.

It has one row for each group that has a non-empty events property. I've then taken a quick look, and:

• if the group is archived, badly obsolete, or undocumented, recommend we delete the events it lists.

• if the events are documented under interfaces that appear under the group's interfaces property (as in the "File API" example above), recommend we delete the events it lists. I've indicated this with "Under own interface".

• if the events are documented under a different interface (as in the "Clipboard API" example above) recommend we keep them and prefix them with the event's associated interface (e.g. "Document: cut"). I've indicated this with "Under other interface".

Most have a clear answer: there are a few that will need a deeper look.

[chrisdavidmills]

@wbamberg this seems reasonsable to me.

[Elchi3]

Sounds good to me, too.

[wbamberg]

GroupData and DefaultAPISidebar updates are now merged and deployed (https://github.com/mdn/kumascript/pull/1136), and pages like https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events and https://developer.mozilla.org/en-US/docs/Web/API/Touch_events are showing what we would expect: