How to represent the introduction of AudioScheduledSourceNode?

[foolip]

As documented, AudioScheduledSourceNode is an abstract interface with concrete inheriting interfaces being AudioBufferSourceNode, OscillatorNode, and ConstantSourceNode. Unfortunately, it originally didn't exist, but was added to the prototype chain during the evolution of the Web Audio API.

The concrete problem in BCD now is that the ended event is represented in multiple places:

• AudioScheduledSourceNode has ended event, onended, start and stop
• AudioBufferSourceNode has onended and start
• OscillatorNode has onended, start and stop
• ConstantSourceNode has onended, start and stop

The data for these differs, and there's plenty wrong with it. But what should it say?

From the point of view of a web developer, the introduction of AudioScheduledSourceNode doesn't matter, what matters is that one can call start(), stop() and listen for the ended event on the 3 concrete audio node types.

This is a specific instance of a more general problem, How to represent changes/moves on the prototype chain. It's the opposite situation to Data for localName/namespaceURI/prefix attributes on Attr/Element/Node is inconsistent/confusing, as here things have moved upwards in the prototype chain, not downwards.

[foolip]

As for a proposed solution in this case, I'd have to say removing the entries from the 3 concrete node types. If we find that event and methods became available at different times on the concrete types, a note on the support data for AudioScheduledSourceNode could explain it. I hope this is now far enough in the past that it doesn't matter in practice.

cc @ddbeck @vinyldarkscratch

[foolip]

For Chromium, the AudioScheduledSourceNode interface was added in https://chromium.googlesource.com/chromium/src/+/00971f38908388728f49cd5127b9c6c6761d035f (M57) but it wasn't just a rename of the interface as the note in https://developer.mozilla.org/en-US/docs/Web/API/AudioScheduledSourceNode#Browser_compatibility would suggest. That change also moved things between interfaces.

[ddbeck]

As for a proposed solution in this case, I'd have to say removing the entries from the 3 concrete node types. If we find that event and methods became available at different times on the concrete types, a note on the support data for AudioScheduledSourceNode could explain it.

This seems reasonable to me. I do have a request though:

To make it easier unstitch the mixins at a later date (should we ever get a good way of handling them), please be pedantic in the notes (e.g., multiple notes, if needed, to say something like, "From X to Y, someevent was implemented as part of OtherInterface." and so on, as you're able to express with the information you have).

[foolip]

This is actually not a case of mixins, although a lot about it is similar to mixin situations. Here, the interface is web-observable, it just doesn't matter so much to web developers where on the prototype chain things are.

[ddbeck]

Oh, I misunderstood (this will teach me to read something like this at the end of the day). 🤦 I'm sorry—I should read these things with more care.

The good news is that I think I might have hit on a solution to interfaces moves.

I spent a while thinking this through but I think the irrelevant features guideline gives us a good way of thinking about API moves:

If the specced behavior is long-standing and consistent between vendors (e.g., if all the browsers have moved the API up the inheritance chain two or more years ago), then we could get away with your proposed solution (i.e., removing them from the inheriting interfaces and only documenting them in the AudioScheduledSourceNode). It'd be nice to note the historic availability of the API on interfaces, but it's just that: a note.

By my thinking, our data guideline allows this already: the feature has been "removed" from the inheriting interfaces (even though a feature of the same name has been added further up the inheritance chain). That is, AudioScheduledSourceNode.ended_event is a distinct feature from api.AudioScheduledSourceNode.ended_event. We have to represent both only as long as the irrelevance guideline says, at which point we can remove the original API.

This works as long as the feature has been "removed" from every browser in the last two years (or never shipped in the first place). If, for example, IE implemented it, then we'd be stuck with having seemingly-duplicate features in two APIs for five years.

That said, it would probably be a good idea to update the irrelevant feature guideline to suggest putting notes when the interface removal is one half of a move, rather than an absolute removal.

[foolip]

Unfortunately, the introduction of AudioScheduledSourceNode is still recent in WebKit, just a few months ago: https://trac.webkit.org/changeset/264538/webkit.

In Chromium, it was early 2017: https://chromium.googlesource.com/chromium/src/+/00971f38908388728f49cd5127b9c6c6761d035f

In Gecko, it was late 2016: mozilla/gecko-dev@bd93c7b#diff-4904f00bab0ff2507512266ffe296647

So the irrelevant features guideline won't help resolve this, at least not for about two years.

To represent this as onended, start and stop having been removed from AudioBufferSourceNode / OscillatorNode / ConstantSourceNode would make it look like one has to be careful about using these APIs, but that's rarely the case. On any instance of AudioBufferSourceNode / OscillatorNode / ConstantSourceNode they are always there. The only thing I can think of that matters in practice is that feature detecting using 'onended' in AudioScheduledSourceNode.prototype won't work before the changes, while 'onended' in AudioBufferSourceNode.prototype would.

Thinking of the eventual state of the data here, if we remove the bits from the 3 concrete interfaces, it's going to be strange that AudioScheduledSourceNode was introduced later than it's possible to use these methods.

The only way I can think of for this to look correct and non-scary to MDN readers is if the entries on AudioScheduledSourceNode are shown inline with the 3 concrete interfaces, and is somehow combined with the other entries of the same name. That's related to #3441.

Sorry I have only problems at this point, no solutions :)

[foolip]

The same issue was raised in #5794. cc @sideshowbarker

[ddbeck]

Copying something relevant over from, #5794, by @Elchi3:

This is probably a duplicate of #3463

Other, maybe related, complicated issues: #472, #3441

Personally, I don't think it's a duplicate of #3463 exactly, more like a specific case of the broader issue.

[foolip]

Right, this is an instance of #3463. Turns out that it might make sense to do things differently depending on how things moved in the prototype chain (tree, actually).

[ddbeck]

To your earlier points, @foolip, I am disappointed my brilliant solution doesn't solve anything. Typical. 😆

I'm taking a new approach then. I'll try to write something up which distributes this a bit more widely, but I had a conversation with Chris Mills today about how to handle muddy questions, like this one, where there's no obvious or consensus solution. So, in general and in the near-term, I'm going to adopt a tendency toward reversibility: handle data in ways that will permit us flexibility. In this time of upheaval for MDN, a guiding principle of "don't make any difficult-to-revert decisions" feels like a good one, even if that leads to some untidiness in the near term.

---

As you originally wrote:

From the point of view of a web developer, the introduction of AudioScheduledSourceNode doesn't matter, what matters is that one can call start(), stop() and listen for the ended event on the 3 concrete audio node types.

And I think that should guide us toward duplication, rather than consolidating on AudioScheduledSourceNode (at least until 5 years have gone by). So here's what I'm thinking: complete all the features on all the interfaces where they have been implemented. This is going to lead to some duplication and noise in the compat tables. But I'd rather be honest with the audience than try to paper over deficiencies in our schema or discard data immediately. It's not a great solution, but I don't think it's a permanent solution either.

So, what does this actually mean?

1. Start by recording the data for AudioScheduledSourceNode as if there was no prototype move and the feature never existed before AudioScheduledSourceNode existed (we'll amend with notes in a bit, hold on).

2. For the concrete interfaces, record the complete history, even the part that has moved up the prototype chain. Use separate support statements for the versions which have moved the prototype chain. For example, two support statements:

   1. version_added: [first version on AudioScheduledSourceNode]
   2. version_added: [first implemented], version_removed: [first version on AudioScheduledSourceNode]

3. Fill out the story with notes:

   • AudioScheduledSourceNode - Notes on the most recent and least recent support statements (if different), noting that support may have predated AudioScheduledSourceNode on concrete interfaces. Link to those concrete interfaces.
   • Concrete interfaces - Notes on the most recent support statements, noting that support is actually via AudioScheduledSourceNode. Link to that feature's MDN page.

I realize this is going to be gnarly. This suggests to me that some tools to help reviewers with interdependent features (i.e., implementing #6571) is going to be especially important. If you think this is a good way to go, then I would prioritize that work after the @mdn package scoping.

What do you think?

[foolip]

@ddbeck that sounds eminently reasonable to me, and I can definitely get behind the "don't make any difficult-to-revert decisions" principle.

I think I'd be able to sort this out without any tooling support. What I'm suggesting in #6571 might even get in the way for this, since from Web IDL we would conclude that AudioBufferSourceNode depends on AudioScheduledSourceNode, which won't be the case here, and an exception to rules based on inheritance would have to be made here.

[foolip]

There's a pattern that could be followed for this in #3463 (comment).

[foolip]

When AudioScheduledSourceNode was added in each browser/engine:

Chromium 57:
https://bugs.chromium.org/p/chromium/issues/detail?id=661207
https://storage.googleapis.com/chromium-find-releases-static/009.html#00971f38908388728f49cd5127b9c6c6761d035f

Firefox 53:
https://bugzilla.mozilla.org/show_bug.cgi?id=1324568
mozilla/gecko-dev@bd93c7b

WebKit trunk 610.1.20, which was Safari 14:
https://bugs.webkit.org/show_bug.cgi?id=214381
https://trac.webkit.org/changeset/264538/webkit

[foolip]

I've sent #9599.