Use consistent naming for "returns a Promise" subfeatures

[foolip]

This matches the style used for api.HTMLMediaElement.play:

browser-compat-data/api/HTMLMediaElement.json

Lines 2739 to 2741 in b49252c

	"returns_promise": {
	"__compat": {
	"description": "Returns a <code>Promise</code>",

Only RTCPeerConnection remains using a different structure, but needs a
lot of changes so is left out of this update.

[foolip]

@ddbeck can you review? I'm not sure if you want a guideline for this?

[ddbeck]

This is interesting. Thankfully it doesn't seem like too many features are affected (if there were lots, I'd give serious consideration to a more fundamental change: there's two distinct APIs—thus two features—that happen to share a name).

Only RTCPeerConnection remains using a different structure

RTCPeerConnection uses deprecated features for callbacks, right? I wonder if that's the right way to do it, or to use partial implementation statement on the parent feature (though that's a little anachronistic). Seems like the old definition of the API ought to become less interesting over time, as the Promise version cements as the correct one.

That said, it's not a lot of features, so I don't feel strongly about this. If you want to apply these changes and stop there, that's better than what we've got and it's worth doing. So take that up if you like, but I'm not going to require it.

I'm not sure if you want a guideline for this?

If this were a one-off, I'd say we don't need a guideline, since a) it won't be an ongoing effort to align these features to each other and b) it shouldn't reoccur, on the expectation that new specs won't coming along that will switch from callbacks to promises.

That said, this won't be fixed up in a single PR, so I'd like to see either a guideline added to this PR or an issue opened to make a paper trail that ties together the overall effort. Basically, I want a single thing to refer to should a question arise about how to structure something like this.

[foolip]

I'll have to come back to this after vacation, don't expect anything in the next two weeks.

[foolip]

There's more of this in #12300, so a guideline is needed now I guess...

[foolip]

@ddbeck this now includes a guideline as well, can you take a look?

[ddbeck]

Looks good. Thank you! 🎉