4 ms·

Array.prototype.slice is specced out by the JS standard. getActiveUniformBlockParameter is part of the DOM. The DOM is specced in terms of interfaces—the only

Array.prototype.slice is specced out by the JS standard. getActiveUniformBlockParameter is part of the DOM. The DOM is specced in terms of interfaces—the only thing that the DOM guarantees is that when you're interacting with an object that satisfies the interface, it will have a getActiveUniformBlockParameter method. WebGL2RenderingContext.prototype.getActiveUniformBlockParameter is a JS-ism and isn't essential to the implementation of the spec.

greggman 9y ago
what? it's required that setting WebGL2RenderingContext.prototype.getActiveUniformBlockParameter to some other function work. You set it before object creation. Objects created indirectly get the new functionality through their prototype. This is true for all DOM objects. maybe I don't understand your distinction
- carussell 9y ago
  > Objects created indirectly get the new functionality through their prototype Except most parts of the DOM in most engines is implemented in C++, not JS. <whatever>.prototype is a JS-ism. But the DOM is not defined in terms of JS. It's defined in terms of a language-agnostic set of interfaces. So when poking around and seeing things like NodeIterator.prototype within JS, you're seeing them because the browser is presenting it to you in a way that kind of resembles the way things work for that runtime. <whatever>.prototype (when <whatever> is some DOM interface) is a byproduct of that behavior. But that those interfaces get implemented is the only essential characteristic of the DOM, and the docs should reflect those interfaces, not the weird and tangential byproducts of how the DOM gets projected into a JS runtime.
  - greggman 9y ago
    I'm not understanding the distinction from a JS programmer's perspective. If I have a = {} a.foo = () => (); foo is a member of a. Where as if I have class A { foo() {} } a = new A(); foo is a member of the prototype for class A. This is important because I need to know if replacing A.prototype.foo will effect all new As or none. Documenting the function is defined on the prototype tells me this. So, I need both Array.prototype.slice and WebGL2RenderingContext.prototype. getActiveUniformBlockParameter documented the same. If WebGL2RenderingContext.prototype.getActiveUniformBlockParameter is only documented as WebGL2RenderingContext.getActiveUniformBlockParameter that suggests to me that I can't do this WebGL2RenderingContext.prototype. getActiveUniformBlockParameter = someNewFunc gl = someCanvas.getContext("webgl2") Instead I must do this gl = someCanvas.getContext("webgl2") gl.getActiveUniformBlockParameter = someNewFunc The first is far more useful because I can effect it indirectly. The second requires me to modified code at creation, code that might be in a 3rd party library. So, if .prototype. is left out of the docs for WebGL2RenderingContext.prototype.getActiveUniformBlockParameter that suggests to me I can't do the first. Seems like those 2 things Array.prototype.slice and WebGL2RenderingContext.prototype.getActiveUniformBlockParameter should be documented consistently. In other words, a JS programmer does not care about implementation details. They don't care one object is a DOM element vs a JS Object (at least not in this case). They care how they can use it in a program. To do that they need to know is the function on the prototype or on the object itself and documenting as Class.prototype.func tells them that.
    - carussell 9y ago
      > foo is a member of a [...] foo is a member of the prototype for class A [...] they need to know is the function on the prototype or on the object itself and documenting as Class.prototype.func tells them that I know how prototypes work, and I know why the `Array.prototype.slice` are documented that way, because I wrote those docs—and caught a bunch of flak along the way when making the move away from referring those and other methods in the form `Array.slice`—in 2007. It's hard to address the issue using your specific example, because it's so contrived. (Who is replacing native implementations [don't], and why? [Once again: don't.]) Here's the actual motivating factor for why you see stuff like `Array.prototype.slice` documented that way: There are methods `fromCharCode` and `charCodeAt`. However, you call the former as `String.fromCharCode` and the latter as `x.charCodeAt`, where `x` is some string instance. That's an important distinction, which means it's important that we not refer to them as `String.fromCharCode` and `String.charCodeAt`. The former is a real method that actually existed, and the latter is something that doesn't exist Which means if we tell readers "Use `String.charCodeAt`", then what we're doing is giving readers bad, confusing, and possibly frustrating information—not what you want when your goal is to be explaining things to an already unsure or simply ignorant audience. This distinction only became more important with ES5, since it started adding things like `Object.keys` and `Object.defineOwnProperty`, rather than making those methods available to all instances by adding them to the prototype. But this is all besides the point, because we're talking about the DOM here. > I'm not understanding the distinction from a JS programmer's perspective That's the problem. Because what we're discussing is a reference for people using the DOM, and once again your changes would force a bunch of JS-isms into the scope of the documentation, and not only that, but a bunch of shaky, not-at-all-well-understood-or-agreed-upon, cobweb-covered parts of how the underlying objects get projected into JS. > In other words, a JS programmer does not care about implementation details. You understand that the thing you're asking for are that implementation details surface through the docs, right? And that they should be a prominent feature? That's what you're asking for.

greggman 9y ago

what? it's required that setting WebGL2RenderingContext.prototype.getActiveUniformBlockParameter to some other function work. You set it before object creation. Objects created indirectly get the new functionality through their prototype. This is true for all DOM objects. maybe I don't understand your distinction

carussell 9y ago
> Objects created indirectly get the new functionality through their prototype Except most parts of the DOM in most engines is implemented in C++, not JS. <whatever>.prototype is a JS-ism. But the DOM is not defined in terms of JS. It's defined in terms of a language-agnostic set of interfaces. So when poking around and seeing things like NodeIterator.prototype within JS, you're seeing them because the browser is presenting it to you in a way that kind of resembles the way things work for that runtime. <whatever>.prototype (when <whatever> is some DOM interface) is a byproduct of that behavior. But that those interfaces get implemented is the only essential characteristic of the DOM, and the docs should reflect those interfaces, not the weird and tangential byproducts of how the DOM gets projected into a JS runtime.
- greggman 9y ago
  I'm not understanding the distinction from a JS programmer's perspective. If I have a = {} a.foo = () => (); foo is a member of a. Where as if I have class A { foo() {} } a = new A(); foo is a member of the prototype for class A. This is important because I need to know if replacing A.prototype.foo will effect all new As or none. Documenting the function is defined on the prototype tells me this. So, I need both Array.prototype.slice and WebGL2RenderingContext.prototype. getActiveUniformBlockParameter documented the same. If WebGL2RenderingContext.prototype.getActiveUniformBlockParameter is only documented as WebGL2RenderingContext.getActiveUniformBlockParameter that suggests to me that I can't do this WebGL2RenderingContext.prototype. getActiveUniformBlockParameter = someNewFunc gl = someCanvas.getContext("webgl2") Instead I must do this gl = someCanvas.getContext("webgl2") gl.getActiveUniformBlockParameter = someNewFunc The first is far more useful because I can effect it indirectly. The second requires me to modified code at creation, code that might be in a 3rd party library. So, if .prototype. is left out of the docs for WebGL2RenderingContext.prototype.getActiveUniformBlockParameter that suggests to me I can't do the first. Seems like those 2 things Array.prototype.slice and WebGL2RenderingContext.prototype.getActiveUniformBlockParameter should be documented consistently. In other words, a JS programmer does not care about implementation details. They don't care one object is a DOM element vs a JS Object (at least not in this case). They care how they can use it in a program. To do that they need to know is the function on the prototype or on the object itself and documenting as Class.prototype.func tells them that.
  - carussell 9y ago
    > foo is a member of a [...] foo is a member of the prototype for class A [...] they need to know is the function on the prototype or on the object itself and documenting as Class.prototype.func tells them that I know how prototypes work, and I know why the `Array.prototype.slice` are documented that way, because I wrote those docs—and caught a bunch of flak along the way when making the move away from referring those and other methods in the form `Array.slice`—in 2007. It's hard to address the issue using your specific example, because it's so contrived. (Who is replacing native implementations [don't], and why? [Once again: don't.]) Here's the actual motivating factor for why you see stuff like `Array.prototype.slice` documented that way: There are methods `fromCharCode` and `charCodeAt`. However, you call the former as `String.fromCharCode` and the latter as `x.charCodeAt`, where `x` is some string instance. That's an important distinction, which means it's important that we not refer to them as `String.fromCharCode` and `String.charCodeAt`. The former is a real method that actually existed, and the latter is something that doesn't exist Which means if we tell readers "Use `String.charCodeAt`", then what we're doing is giving readers bad, confusing, and possibly frustrating information—not what you want when your goal is to be explaining things to an already unsure or simply ignorant audience. This distinction only became more important with ES5, since it started adding things like `Object.keys` and `Object.defineOwnProperty`, rather than making those methods available to all instances by adding them to the prototype. But this is all besides the point, because we're talking about the DOM here. > I'm not understanding the distinction from a JS programmer's perspective That's the problem. Because what we're discussing is a reference for people using the DOM, and once again your changes would force a bunch of JS-isms into the scope of the documentation, and not only that, but a bunch of shaky, not-at-all-well-understood-or-agreed-upon, cobweb-covered parts of how the underlying objects get projected into JS. > In other words, a JS programmer does not care about implementation details. You understand that the thing you're asking for are that implementation details surface through the docs, right? And that they should be a prominent feature? That's what you're asking for.