Skip to content
This repository has been archived by the owner on Jan 24, 2024. It is now read-only.

Update DefaultAPISidebar macro for new event organisation #1314

Closed
wbamberg opened this issue Apr 11, 2019 · 8 comments
Closed

Update DefaultAPISidebar macro for new event organisation #1314

wbamberg opened this issue Apr 11, 2019 · 8 comments
Assignees
Labels
Cf:Med Confidence: Medium

Comments

@wbamberg
Copy link

This is a work item for #685, and was originally discussed in #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:

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

@wbamberg wbamberg added the Cf:Med Confidence: Medium label Apr 11, 2019
@wbamberg wbamberg added this to the India.Arie (S2 Q2 2019) milestone Apr 11, 2019
@wbamberg wbamberg self-assigned this Apr 11, 2019
@wbamberg wbamberg changed the title Update DefaultAPISidebar for new event organisation Update DefaultAPISidebar macro for new event organisation Apr 11, 2019
@wbamberg
Copy link
Author

wbamberg commented Apr 27, 2019

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:


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
Copy link

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
Copy link
Author

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.

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
Copy link
Author

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

@wbamberg
Copy link
Author

wbamberg commented Apr 29, 2019

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
Copy link
Contributor

@wbamberg this seems reasonsable to me.

@Elchi3
Copy link
Member

Elchi3 commented Apr 29, 2019

Sounds good to me, too.

@wbamberg
Copy link
Author

wbamberg commented May 9, 2019

GroupData and DefaultAPISidebar updates are now merged and deployed (mdn/kumascript#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:

Screen Shot 2019-05-09 at 1 59 11 PM

Screen Shot 2019-05-09 at 1 59 20 PM

@wbamberg wbamberg closed this as completed May 9, 2019
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Cf:Med Confidence: Medium
Projects
None yet
Development

No branches or pull requests

6 participants
@chrisdavidmills @Elchi3 @wbamberg @jmswisher @ExE-Boss and others