get-buffer-source-{reference,copy} ought to point to the algorithm

[equalsJeffH]

WebCryptoAPI uses this link -- https://heycam.github.io/webidl/#dfn-get-buffer-source-copy -- (and WebAuthn has been advised to do so also), which points into this WebIDL paragraph:

https://github.com/heycam/webidl/blob/83448a73bec7f84b930fd3b8ef0a8365d5457695/index.bs#L6021-L6027

..although said paragraph actually does not say how one might go about getting said copy (or reference). Subsequent poking through WebIDL yields this algorithm..

https://github.com/heycam/webidl/blob/83448a73bec7f84b930fd3b8ef0a8365d5457695/index.bs#L7945

..which does point back to the former paragraph. It seems to me the paragraph ought to also link to the algorithm.

[domenic]

This is just an artifact of Web IDL's wonky splint into language-independent concepts ("get a copy of the bytes held by the buffer source") and ECMAScript bindings (the algorithm you found).

It's correct for specs to link to the language-independent concepts. One day we will squish them together, but for now this just parallels the rest of the spec. E.g. the definition of the language independent "double" type doesn't forward-link to the specific way that you might get a double given an ECMAScript environment.

[equalsJeffH]

Thanks for the explanation, though this asymmetry arguably steepens the WebIDL learning curve -- at least it does so for me.

[domenic]

Yep, it's a medium-term goal to squash together the language-independent and JS-language-binding sections into one; it's unnecessary abstraction at this point. (Back in the deep past there were Java bindings...)

[tobie]

Wonder if WebAssembly won't come and ruin that nifty plan, though.

[annevk]

1. We should not let WebAssembly guide our design here. Once WebAssembly is ready to integrate with more of the platform, we should at that point see what delta we need to make. We've learned time and again that designing factories fails and actually constrain the solution space.
2. The real solution to this problem is https://www.w3.org/Bugs/Public/show_bug.cgi?id=28798 which I hope we can get to somewhat soonish (we should, because it soon will be more complicated with buffers shared across threads). The way we deal with bytes at the IDL layer today is rather old-fashioned.

[annevk]

This was fixed by #987.