Completely Undocumented DOM Class: dispHTMLElementCollection

[blakeyrat]

If reading the documentation doesn't lead me to the correct understanding, then the documentation is flawed.

[boomzilla]

@blakeyrat said:

If reading the documentation doesn't lead me to the correct understanding, then the documentation is flawed.

Could you let us know what else you don't understand, so that we can see what else is flawed?

Since everyone else here seems to understand the documentation, it hasn't occurred to you that the problem might be you?

[Ilya_Ehrenburg]

@blakeyrat said:

If I see "string" as a type in the debugger, I expect "string" to be in the documentation. If I see "int" as a type in the debugger, I expect "int" to be in the documentation. If I see "dispHTMLElementCollection" in the debugger, I expect "dispHTMLElementCollection" to be documented.

That expectation is exaggerated. It is acceptable that there is no API documentation for an opaque type whose only purpose is to implement an interface and which is not intended to be directly accessible to users of the library. Though it is preferable that it would be documented as "class XY: implements interface AB", it being undocumented is not a WTF, rather a "tsk!".

@blakeyrat said:

If dispHTMLElementCollection is the interface to NodeList,

The other way round, NodeList is the interface by which you access a dispHTMLElementCollection.

@blakeyrat said:

then there should be a bit of documentation that says that. I don't see how that's controversial. I really, honestly, truly-to-God, don't get why that shouldn't exist.

 

I don't say it [i]shouldn't[/i] exist, just that it's not absolutely necessary that it exists.

All you need to know about the result of getElementsByTagName is that it returns an object of a class implementing NodeList. Everything else is irrelevant, as the implementation details are likely to change across browsers, even browser versions, anyway.

Now, it's nice if the way from the debugger output to that knowledge is clearly marked, but it's sufficient if it's easily findable.

It is, so "tsk!", not "wtf".

[joeshmo21]

I wouldn't even call it a "tsk!" That's like saying you need to document an anonymous inner class in Java as implementing an interface, or documenting an anonymous delegate in C#. It isn't necessary, it is implied by the return type of the method.

[Guest]

The real question here is: why are you calling getElementsByName when you pretend to not already know what it is supposed to return? Are you just firing wildly in the dark, trying functions that sound like the right ones without consulting the documentation on them? And if so, why does the lack of documentation all of a sudden bother you?

[Ilya_Ehrenburg]

@joeshmo21 said:

I wouldn't even call it a "tsk!" That's like saying you need to document an anonymous inner class in Java as implementing an interface, or documenting an anonymous delegate in C#. It isn't necessary, it is implied by the return type of the method.

 

I'd say it depends on the circumstances. If that inner class is what a widely used method returns, it's more user-friendly to have it in the docs, so IMO, it qualifies as a "tsk!" (which is a very mild form of disapproval). If it is only internally used, it's better to not have it in the docs.

[joeshmo21]

@Ilya Ehrenburg said:

I'd say it depends on the circumstances. If that inner class is what a widely used method returns, it's more user-friendly to have it in the docs, so IMO, it qualifies as a "tsk!" (which is a very mild form of disapproval). If it is only internally used, it's better to not have it in the docs.

 

I don't know about that. With any (good) API, you don't want to let clients know any more than they need. Everything should be disclosed on a strict need-to-know basis. If your method guarantees you are returning a NodeList, and you are returning a subclass of NodeList, then this is all the documentation a client needs to see. The contract is fulfilled. You don't want to document internal implementations because 1) the client shouldn't care and 2) you have to remember to change the documentation for the method if you switch implementations. Depending on circumstances, of course, it is a good idea to comment this in your code internally so that future maintainers of your application know what is going on, but if an outside client interfaces with it, don't bother revealing details in API docs.

[joeshmo21]

@Ilya Ehrenburg said:

If it is only internally used, it's better to not have it in the docs.

 

I'm sorry, I just realized I misread that, and I essentially repeated part of what you said.

[PJH]

@boomzilla said:

@blakeyrat said:

If reading the documentation doesn't lead me to the correct understanding, then the documentation is flawed.

Could you let us know what else you don't understand, so that we can see what else is flawed?

Since everyone else here seems to understand the documentation, it hasn't occurred to you that the problem might be you?

4 days later and this is *still* going on?

Googling a couple of terms in the OP's *1st* post gave me the documentation the OP is so sadly lacking - the source code. At least to the interfaces concerned.

[bstorer]

@Ilya Ehrenburg said:

@joeshmo21 said:

I wouldn't even call it a "tsk!" That's like saying you need to document an anonymous inner class in Java as implementing an interface, or documenting an anonymous delegate in C#. It isn't necessary, it is implied by the return type of the method.

 

I'd say it depends on the circumstances. If that inner class is what a widely used method returns, it's more user-friendly to have it in the docs, so IMO, it qualifies as a "tsk!" (which is a very mild form of disapproval). If it is only internally used, it's better to not have it in the docs.

I'd view this as being similar to how Java's documentation handles these things.  For example, there's no documentation* on SunGraphics2D, but it's probably what you'll get back from calling getGraphics() on a Swing Component.  The reason?  Because the implementation doesn't matter.  The documentation on getGraphics() says it returns a Graphics object, that's how you use it, end of story.  Sure, I can find out the class's name, just as blakeyrat's debugger will tell him the name of the NodeList class, but I should already know how to use it, and typically should only be peeking at its name out of curiousity.

*There's documentation on it out there since Sun opened up a bunch of the source, but it's not in the Java API (and we're discussing APIs).

[Ilya_Ehrenburg]

@joeshmo21 said:

I don't know about that. With any (good) API, you don't want to let clients know any more than they need. Everything should be disclosed on a strict need-to-know basis. If your method guarantees you are returning a NodeList, and you are returning a subclass of NodeList, then this is all the documentation a client needs to see. The contract is fulfilled. You don't want to document internal implementations because 1) the client shouldn't care and 2) you have to remember to change the documentation for the method if you switch implementations. Depending on circumstances, of course, it is a good idea to comment this in your code internally so that future maintainers of your application know what is going on, but if an outside client interfaces with it, don't bother revealing details in API docs.

 

You misunderstood me. In the method docs, have "returns interface A", nothing else. For the reasons you gave.

But take the following scenario:

You have code that doesn't do what you think it would do, but you haven't been told by a compiler why (might even be purely a performance issue).

You go and debug the code, for example, you have the line

A res = method(params);

and add debugging output

System.err.println("Result of method has type " + res.getClass().getName());

You read the output "Result of method has type FancyClass".

(or you run it in a debugger and the debugger tells you that)

Then it'd be nice if you can go to the API docs, search for "FancyClass" and find a page that tells you

class FancyClass implements interface A (more if that class is intended for public use).

 

Yes, the proper way to go about it is to first check the docs for method(), but if method() returns a Collection, it might shed light on the issues to know if it's a HashSet or a TreeSet or what. And if it's a UseOnlyForMethodSet, you might want to look if any performance guarantees are given nevertheless, so it's nicer to have the class in the docs, but not necessary.

[joeshmo21]

 I did misunderstand you. Sorry!

[Ilya_Ehrenburg]

@joeshmo21 said:

 I did misunderstand you. Sorry!

 

No problem, happens all the time. You noticed that while I typed and I didn't check for new posts when I'd finished. Sorry for that.

[rohypnol]

@joeshmo21 said:

 The problem isn't documentation, it is your understanding of API design. And why are you so hostile? I'm trying to help you in the nicest way I know how, by offering useful advice.

 

...unlike me :( now you made me feel guilty

[fbmac]

@blakeyrat Found this as your oldest topic posted here (looking for a good rant, as you always deliver), and got amused with this on your blog:

Ok, so I posted this to TheDailyWTF, thinking it’d be a laugh: it’s not. Don’t do that, ever. You’d never know it from the frontpage, but the WTF forums are full, apparently, of programmers with psychic or telekinetic powers.

[Tsaukpaetra]

@blakeyrat said in Completely Undocumented DOM Class: dispHTMLElementCollection:

It looks like an
array, it walks like an array, and it quacks like a duck, but it’s not
actually an array at all.

Nope, it's a dock. ;)

[cartman82]

Some things never change.

Like, war. And blakeyrat not understanding things and causing everyone to call him an idiot.

Mostly blakeyrat, actually.

[Magus]

On my third refresh just now:

Cool website, bro. Gonna refresh again now I guess. It's back to normal, but there's a forum updated notification AGAIN.

[Tsaukpaetra]

@Magus said in Completely Undocumented DOM Class: dispHTMLElementCollection:

On my third refresh just now:

Totes missed my update in the Status thread then... ;)

[anonymous234]

Blakey seems mostly right here, a type that has a different name in every interpreter seems like a and a huge way to confuse users with no apparent benefit.

[anotherusername]

@anonymous234 you have to realize that it was 7 years ago, which was before browsers got their heads together and standardized on stuff like that. Currently, does

document.getElementsByTagName("a").toString();

produce [object HTMLCollection] in your browser of choice? I just tested Chrome, Firefox, and IE, and they all do. Or,

document.getElementsByTagName("a") instanceof HTMLCollection;

...which should produce true.

Also note that the DOM Level 1 specification, dated 1 October, 1998, says that getElementsByTagName should return a NodeList, not a dispHTMLElementCollection. And no DOM specification since then has ever said it should return anything else until it changed to a HTMLCollection, which is what it is now. So if there was screwy browser-specific stuff going on, it isn't because there weren't standard DOM specifications, it's because browsers like IE weren't following the specs.

[Medinoc]

This thread made me notice, I've been working with .Net (and before that, COM) for so long that now I have trouble noticing that a type not starting with I can be an interface until pointed out.

[Medinoc]

@anotherusername said in Completely Undocumented DOM Class: dispHTMLElementCollection:

@anonymous234 you have to realize that it was 7 years ago, which was before browsers got their heads together and standardized on stuff like that. Currently, does

document.getElementsByTagName("a").toString();

produce [object HTMLCollection] in your browser of choice? I just tested Chrome, Firefox, and IE, and they all do. Or,

document.getElementsByTagName("a") instanceof HTMLCollection;

...which should produce true.

Also note that the DOM Level 1 specification, dated 1 October, 1998, says that getElementsByTagName should return a NodeList, not a dispHTMLElementCollection. And no DOM specification since then has ever said it should return anything else until it changed to a HTMLCollection, which is what it is now. So if there was screwy browser-specific stuff going on, it isn't because there weren't standard DOM specifications, it's because browsers like IE weren't following the specs.

Uhm, you do realize that as long as the specs said NodeList, IE was in the right, right? When a function is documented to return an interface, the implementation can be any class the implementer chooses.

[dkf]

@Medinoc said in Completely Undocumented DOM Class: dispHTMLElementCollection:

I've been working with .Net (and before that, COM) for so long that now I have trouble noticing that a type not starting with I can be an interface until pointed out.

Why would you care most of the time? The IDE will know (particularly if you're inheriting/implementing the class/interface, which is when it really matters) but most of the time you just care that it's following a protocol of usage. It's pretty much an antipattern to actually care exactly what class you've got an instance of, as it really buggers up the LSP…

[Medinoc]

@dkf said in Completely Undocumented DOM Class: dispHTMLElementCollection:

@Medinoc said in Completely Undocumented DOM Class: dispHTMLElementCollection:

I've been working with .Net (and before that, COM) for so long that now I have trouble noticing that a type not starting with I can be an interface until pointed out.

Why would you care most of the time? The IDE will know (particularly if you're inheriting/implementing the class/interface, which is when it really matters) but most of the time you just care that it's following a protocol of usage. It's pretty much an antipattern to actually care exactly what class you've got an instance of, as it really buggers up the LSP…

I don't care when I dev because I dev in C# anyway (plus, I use Visual C#'s color options to make such things obvious there) but when I have to read someone else's code, knowing what is an interface and what isn't helps figuring out what is "expected" to be overridden and what isn't. Tells a lot about how the project is organized.

[anotherusername]

@Medinoc said in Completely Undocumented DOM Class: dispHTMLElementCollection:

Uhm, you do realize that as long as the specs said NodeList, IE was in the right, right? When a function is documented to return an interface, the implementation can be any class the implementer chooses.

I disagree. The spec says it returns a NodeList. IE demonstrably did not return a NodeList, it returned something that behaved similarly but was a dispHTMLElementCollection.

What's the point of the spec saying that something returns a NodeList or throws a DOMException or returns a DocumentFragment if implementations can choose whatever the hell names they want for object classes?

[dkf]

@anotherusername said in Completely Undocumented DOM Class: dispHTMLElementCollection:

The spec says it returns a NodeList.

You are aware of what that means? There's no requirement for the object returned to support any way of saying what its class is; the requirement is that there is a readable length property, and that the individual members of the list can be retrieved by zero-based index. That's it. Anything beyond that (including making it look like something nicely iterable in your favourite language) is entirely outside the spec; relying on non-spec stuff just gets you into trouble.

[blakeyrat]

@Medinoc Oh good. Someone restarted a like 8 year old debate and now I'm getting drowned in notifications for it. Exactly what I wanted.

The point was, I see "dispHTMLElementCollection" in the debugger and it wasn't in the documentation. Any documentation, not Microsoft's, or the W3Cs, or Netscape's or anybody's. That's obviously a bug somewhere. If it shows up in a debugger, it's a type that a user of the language can come across-- if it's a type the user of the language could come across, it needs a documentation page.

Even if the documentation page merely said, "this class is the same as the W3C NodeList as defined here: (link)." I would have been satisfied. Because it'd have been documented. It wasn't.

[anotherusername]

@dkf said in Completely Undocumented DOM Class: dispHTMLElementCollection:

There's no requirement for the object returned to support any way of saying what its class is;

obj instanceof NodeList

isn't a thing anymore?

What about if I wanted to modify the prototype... the spec says it's a NodeList, so I should be able to do like this:

NodeList.prototype.newFunc = ...

Now you're saying that I get no confidence that the class name is actually NodeList like the spec says it is, so instead of that, I now need to do this:

var dummyNodeListObj = funcReturnsNodeList(arg);
var realNodeList = dummyNodeListObj.constructor.prototype;
realNodeList.newFunc = ...

...but why? The spec said it returns a NodeList. It should. If it does not, things that should work do not work anymore.

[dkf]

@anotherusername said in Completely Undocumented DOM Class: dispHTMLElementCollection:

What about if I wanted to modify the prototype... the spec says it's a NodeList, so I should be able to do like this:

The spec isn't written in Javascript at all (but rather in IDL) so now you're projecting and going beyond it.

[anotherusername]

@dkf but it says right here that my scripts should be able to access and manipulate the content:

The functionality specified in this section (the Core functionality) should be sufficient to allow software developers and web script authors to access and manipulate parsed HTML and XML content inside conforming products.

I'm trying to access and manipulate the content with a script. If a browser doesn't use the class name that the spec says it should use for an object, it complicates things, as I just showed.

[dkf]

@anotherusername said in Completely Undocumented DOM Class: dispHTMLElementCollection:

If a browser doesn't use the class name that the spec says it should use for an object

But why are you making your code dependent on the class name? That's just very strange.

Also, if you're monkey-patching stuff into system classes then you should DIE IN A FIRE. Or be forced to support production deployments of Ruby on Rails.

[anotherusername]

@dkf I know it's not best practice, but is there any reason given within the spec that says I should not be able to do it?

[dkf]

@anotherusername There you go again, reading in stuff that isn't there. The spec doesn't exhaustively list everything you can do, it describes the minimum set. There may be other things in the implementation but they're features of the implementation and not of the specification itself.

[anotherusername]

@dkf they're part of ECMAScript, with which the DOM spec specifically says its naming conventions are meant to be compatible...

1.1.3. Naming Conventions

While it would be nice to have attribute and method names that are short, informative, internally consistent, and familiar to users of similar APIs, the names also should not clash with the names in legacy APIs supported by DOM implementations. Furthermore, both OMG IDL and ECMAScript have significant limitations in their ability to disambiguate names from different namespaces that makes it difficult to avoid naming conflicts with short, familiar names. So, DOM names tend to be long and quite descriptive in order to be unique across all environments.

So why should an implementation of the spec be allowed to completely break ECMAScript's instanceof operator?

[wft]

Are you all daft, bickering over a 7 years old topic and throwing the same tired arguments around?

All that was asked was to have it somewhere in documentation that yes, there is this class, you shouldn't be using it directly, because REASONS, but you can come across it in a debugger, so just for your information, here's what interfaces it implements: ...., NodeList, ..., HTMLCollection, ..... . And that's it.

Using it directly in the code itself is a WTF (and so is checking class name), one should just assume it quacks like a HTMLCollection (and use Array.fromArray() if a true array is needed).

Because if it's oh so secret that nobody should evah see it, look, why do they expose it in the debugger?

[anotherusername]

@wft said in Completely Undocumented DOM Class: dispHTMLElementCollection:

and use Array.fromArray() if a true array is needed

I think you mean [...].

[Medinoc]

@anotherusername said in Completely Undocumented DOM Class: dispHTMLElementCollection:

@Medinoc said in Completely Undocumented DOM Class: dispHTMLElementCollection:
I disagree. The spec says it returns a NodeList. IE demonstrably did not return a NodeList, it returned something that behaved similarly but was a dispHTMLElementCollection.

What's the point of the spec saying that something returns a NodeList or throws a DOMException or returns a DocumentFragment if implementations can choose whatever the hell names they want for object classes?

NodeList was documented as an interface, not a class. Interfaces are implemented by classes.
(normally, obj instanceof SomeInterface returns true for any class that implements it)

[anotherusername]

@Medinoc said in Completely Undocumented DOM Class: dispHTMLElementCollection:

normally, obj instanceof SomeInterface returns true for any class that implements it

Isn't that basically what I said? But it requires the class to be named SomeInterface, otherwise the result will be false.

(: it's inaccurate to say instanceof "returns"; it's an operator, not a function.)

[Medinoc]

@anotherusername said in Completely Undocumented DOM Class: dispHTMLElementCollection:

@Medinoc said in Completely Undocumented DOM Class: dispHTMLElementCollection:

normally, obj instanceof SomeInterface returns true for any class that implements it

Isn't that basically what I said? But it requires the class to be named SomeInterface, otherwise the result will be false.

In this case, it's not the library that's broken, it's the entire language. I can't think, or even imagine, any other language that would have this ridiculous requirement (and how is it even possible to give the same name to an interface and a class?)
ETA: And it would also prevent a class from implementing several interfaces.

[anotherusername]

@Medinoc Javascript doesn't have either "interfaces" or "classes", truly. It has functions and objects, and object prototypes which are functions and return objects. So having an "interface" or "class" named such-and-such really just means having a function named such-and-such which can be used to construct an object of typeof such-and-such.

(Well, it does now have classes... sort of... but they're really just syntactic sugar over what it already had.)

[Medinoc]

@anotherusername said in Completely Undocumented DOM Class: dispHTMLElementCollection:

@Medinoc Javascript doesn't have either "interfaces" or "classes", truly. It has functions and objects, and object prototypes which are functions and return objects. So having an "interface" or "class" named such-and-such really just means having a function named such-and-such which can be used to construct an object of typeof such-and-such.

(Well, it does now have classes... sort of... but they're really just syntactic sugar over what it already had.)

Ah, now I understand better. Javascript is trying to do object-oriented, but doesn't actually have a concept of type hierarchy, meaning instanceof only works for the object's actual class (making it next to useless) instead of a class and all the interfaces it implements?

Edit: It's high time I go home now, so don't be surprised if I don't reply in a while.

[Yamikuronue]

@Medinoc It doesn't have types. It's prototypical inheritance.

instanceof - JavaScript | MDN

The instanceof operator tests to see if the prototype property of a constructor appears anywhere in the prototype chain of an object. The return value is a boolean value. Its behavior can be customized with Symbol.hasInstance.

The onbox has the sentence I wanted to point out: "in its prototype chain". So an object has a prototype, which is an object itself, and thus can have a prototype itself.

[anotherusername]

@Medinoc said in Completely Undocumented DOM Class: dispHTMLElementCollection:

Ah, no I understand better. Javascript is trying to do object-oriented, but doesn't actually have a concept of type hierarchy?

Basically. Type hierarchy has been shoe-horned in through prototypes.

@Medinoc said in Completely Undocumented DOM Class: dispHTMLElementCollection:

meaning instanceof only works for the object's actual class (making it next to useless) instead of a class and all the interfaces it implements?

...no... instanceof steps up the prototype chain, and results in true if any match is found:

(__proto__ is not really supposed to be used, but it'll show the prototype chain well enough for this example. Note that IE doesn't appear to have EventTarget at all, so that's missing from the document object's prototype chain on IE.)