Completely Undocumented DOM Class: dispHTMLElementCollection



  •  (Copied from my blog at http://blakeyrat.com/index.php/2009/04/gigantic-javascript-wtf-disphtmlelementcollection/)

    It turns out that the thing getElementsByName and getElementsByTagName returns isn’t actually an array. 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. It’s actually a “dispHTMLElementCollection”.

    I’ve been doing tons and tons of Javascript work for years, and I’ve actually never come up against this particular quirk before. The only reason I figured it out is that I tried to push() an element into a dispHTMLElementCollection, and it turns out that dispHTMLElementCollections don’t have a push() method. Why doesn’t it have a push() method? Who knows.

    Oh, and to make it worse: it’s not documented. Anywhere. This forum post is all MSDN (Microsoft’s developer site, maker of the most popular web browser on Earth) has. Mozilla (makers of the second-most popular web browser on Earth) has absolutely nothing on it, or at least nothing Google’s indexed. Nor does w3.org, the maintainers of the DOM standards.

    What. The. F.

    How it is even possible after the last decade of constant complaining and moaning about web standards support that both IE and Firefox have a completely undocumented DOM class?

    Here’s a test page to demonstrate the issue:

    <form name="form1" method="post" action="PlainText.aspx?id=fb3d2e25-e9d4-493f-92c3-6a313e1529ce" id="form1">
    <input name="__VIEWSTATE" id="__VIEWSTATE" value="/wEPDwUKMTYyNzcxNDY4Ng9kFgICAw9kFgICAQ8WAh4EVGV4dAWnDyZsdDtodG1sJmd0Ow0KJmx0O2hlYWQmZ3Q7DQombHQ7dGl0bGUmZ3Q7VGVzdCZsdDsvdGl0bGUmZ3Q7DQombHQ7L2hlYWQmZ3Q7DQombHQ7Ym9keSZndDsNCg0KJmx0O3AmZ3Q7aCZsdDsvcCZndDsNCiZsdDtwJmd0O2UmbHQ7L3AmZ3Q7DQombHQ7aHIgLyZndDsNCiZsdDtwJmd0O2wmbHQ7L3AmZ3Q7DQombHQ7cCZndDtsJmx0Oy9wJmd0Ow0KJmx0O2hyIC8mZ3Q7DQombHQ7cCZndDtvJmx0Oy9wJmd0Ow0KDQombHQ7c2NyaXB0IHR5cGU9InRleHQvamF2YXNjcmlwdCImZ3Q7DQoNCgkvLyBDYWxsIHRoZSAiYnJva2VuIiB2ZXJzaW9uIG9mIENvbWJpbmVkRWxlbWVudExpc3QNCgkvLyBUaGlzIGZ1bmN0aW9uIGZhaWxzIGluIGJvdGggSUUgYW5kIEZpcmVmb3gsIGV2ZW4NCgkvLyB0aG91Z2ggYXQgZmlyc3QgZ2xhbmNlIGl0IGxvb2tzIGZpbmUuIFJlYXNvbj8NCgkvLyBnZXRFbGVtZW50c0J5VGFnTmFtZSAqZG9lc24ndCogcmV0dXJuIGFuIGFycmF5LA0KCS8vIGluc3RlYWQgaXQgcmV0dXJucyBhICJkaXNwSFRNTEVsZW1lbnRDb2xsZWN0aW9uIg0KCS8vIHdoaWNoIGxvb2tzIGFuZCBhY3RzIGV4YWN0bHkgbGlrZSBhbiBhcnJheSwgYnV0DQoJLy8gaGFzIG5vIC5wdXNoKCkgbWV0aG9kLg0KDQoJLy92YXIgY29tYm8gPSBDb21iaW5lZEVsZW1lbnRMaXN0QnJva2VuKCk7DQoNCgkvLyBUaGUgImZpeGVkIiB2ZXJzaW9uIHVzZXMgYSBKYXZhc2NyaXB0IGFycmF5IHRvDQoJLy8gc3RvcmUgdGhlIHJlc3VsdHMgb2YgdGhlIHR3bw0KCS8vIGdldEVsZW1lbnRzQnlUYWdOYW1lIGNhbGxzLg0KDQoJdmFyIGNvbWJvID0gQ29tYmluZWRFbGVtZW50TGlzdFdvcmtzKCk7DQoNCglhbGVydChjb21iby5sZW5ndGgpOyAvLyBFeHBlY3Q6IDcNCg0KCWZ1bmN0aW9uIENvbWJpbmVkRWxlbWVudExpc3RCcm9rZW4oKQ0KCXsNCgkJLy8gQ3JlYXRlIHR3byAiYXJyYXlzIiBvZiBIVE1MIGVsZW1lbnRzDQoJCXZhciBwYXJhcyA9IGRvY3VtZW50LmdldEVsZW1lbnRzQnlUYWdOYW1lKCdQJyk7DQoJCXZhciBocnMgPSBkb2N1bWVudC5nZXRFbGVtZW50c0J5VGFnTmFtZSgnSFInKTsNCgkJDQoJCS8vIEF0dGVtcHQgdG8gY29tYmluZSB0aGUgdHdvIHVzaW5nIGEgc2ltcGxlIEZPUiBsb29wDQoJCWZvciAodmFyIGkgPSAwOyBpICZsdDsgaHJzLmxlbmd0aDsgaSsrKQ0KCQl7DQoJCQkvLyBJRTogT2JqZWN0IGRvZXNuJ3Qgc3VwcG9ydCB0aGlzIHByb3BlcnR5IG9yIG1ldGhvZA0KCQkJLy8gRmlyZWZveDogcGFyYXMucHVzaCBpcyBub3QgYSBmdW5jdGlvbg0KCQkJcGFyYXMucHVzaChocnNbaV0pOw0KCQl9DQoNCgkJcmV0dXJuIChwYXJhcyk7DQoJfQ0KDQoJZnVuY3Rpb24gQ29tYmluZWRFbGVtZW50TGlzdFdvcmtzKCkNCgl7DQoJCS8vIENyZWF0ZSB0d28gImFycmF5cyIgb2YgSFRNTCBlbGVtZW50cw0KCQl2YXIgcGFyYXMgPSBkb2N1bWVudC5nZXRFbGVtZW50c0J5VGFnTmFtZSgnUCcpOw0KCQl2YXIgaHJzID0gZG9jdW1lbnQuZ2V0RWxlbWVudHNCeVRhZ05hbWUoJ0hSJyk7DQoJCQ0KCQkvLyBDcmVhdGUgYSB0aGlyZCwgYmxhbmssIGFycmF5IHRvIHN0b3JlIHRoZSBjb21iaW5lZCBsaXN0DQoJCXZhciBjb21iaW5lZEFyciA9IG5ldyBBcnJheSgpOw0KCQkNCgkJLy8gUHV0cyBlbGVtZW50cyBmcm9tIHRoZSBmaXJzdCAiYXJyYXkiIGludG8gdGhlIGNvbWJpbmVkIGFycmF5DQoJCWZvciAodmFyIGkgPSAwOyBpICZsdDsgcGFyYXMubGVuZ3RoOyBpKyspDQoJCXsNCgkJCWNvbWJpbmVkQXJyLnB1c2gocGFyYXNbaV0pOw0KCQl9DQoJCQ0KCQkvLyBBbmQgdGhlIHNlY29uZA0KCQlmb3IgKHZhciBpID0gMDsgaSAmbHQ7IGhycy5sZW5ndGg7IGkrKykNCgkJew0KCQkJY29tYmluZWRBcnIucHVzaChocnNbaV0pOw0KCQl9DQoNCgkJcmV0dXJuIChjb21iaW5lZEFycik7DQoJfQ0KDQombHQ7L3NjcmlwdCZndDsNCg0KJmx0Oy9ib2R5Jmd0Ow0KJmx0Oy9odG1sJmd0O2RknKs38NZ5kTuZS3ZfDIY0r5Tk6/c=" type="hidden">
    <pre id="bt_plainText" style="border: 0px none ; margin: 0px; padding: 0px;">&lt;html&gt;<br>&lt;head&gt;<br>&lt;title&gt;Test&lt;/title&gt;<br>&lt;/head&gt;<br>&lt;body&gt;<br><br>&lt;p&gt;h&lt;/p&gt;<br>&lt;p&gt;e&lt;/p&gt;<br>&lt;hr /&gt;<br>&lt;p&gt;l&lt;/p&gt;<br>&lt;p&gt;l&lt;/p&gt;<br>&lt;hr /&gt;<br>&lt;p&gt;o&lt;/p&gt;<br><br>&lt;script type="text/javascript"&gt;<br><br>	// Call the "broken" version of CombinedElementList<br>	// This function fails in both IE and Firefox, even<br>	// though at first glance it looks fine. Reason?<br>	// getElementsByTagName *doesn't* return an array,<br>	// instead it returns a "dispHTMLElementCollection"<br>	// which looks and acts exactly like an array, but<br>	// has no .push() method.<br><br>	//var combo = CombinedElementListBroken();<br><br>	// The "fixed" version uses a Javascript array to<br>	// store the results of the two<br>	// getElementsByTagName calls.<br><br>	var combo = CombinedElementListWorks();<br><br>	alert(combo.length); // Expect: 7<br><br>	function CombinedElementListBroken()<br>	{<br>		// Create two "arrays" of HTML elements<br>		var paras = document.getElementsByTagName('P');<br>		var hrs = document.getElementsByTagName('HR');<br>		<br>		// Attempt to combine the two using a simple FOR loop<br>		for (var i = 0; i &lt; hrs.length; i++)<br>		{<br>			// IE: Object doesn't support this property or method<br>			// Firefox: paras.push is not a function<br>			paras.push(hrs[i]);<br>		}<br><br>		return (paras);<br>	}<br><br>	function CombinedElementListWorks()<br>	{<br>		// Create two "arrays" of HTML elements<br>		var paras = document.getElementsByTagName('P');<br>		var hrs = document.getElementsByTagName('HR');<br>		<br>		// Create a third, blank, array to store the combined list<br>		var combinedArr = new Array();<br>		<br>		// Puts elements from the first "array" into the combined array<br>		for (var i = 0; i &lt; paras.length; i++)<br>		{<br>			combinedArr.push(paras[i]);<br>		}<br>		<br>		// And the second<br>		for (var i = 0; i &lt; hrs.length; i++)<br>		{<br>			combinedArr.push(hrs[i]);<br>		}<br><br>		return (combinedArr);<br>	}<br><br>&lt;/script&gt;<br><br>&lt;/body&gt;<br>&lt;/html&gt;</pre>
    </form>


  • Not a WTF. It's widely documented that getElementsBy* returns a node list object, not an array. The actual class name is different in different browsers (Opera - NodeList, Firefox - HTMLCollection). dispHTMLElementCollection seems to be the IE equivalent.

    Having said that,

    alert(Object.prototype.toString.call( document.getElementsByTagName("h1") ));

    returns 'Object' in IE. But it doesn't matter what it's called, it works the same way. And doesn't support the push method.



  • Indeed. It is not a WTF at all, and it is extremely well documented in the DOM specifications: getElementsByTagName

    "Returns a NodeList"

    interface NodeList {
      Node               item(in unsigned long index);
      readonly attribute unsigned long    length;
    };

    "The items in the NodeList are accessible via an integral index, starting from 0."

    The object is just a regular object, with numerical properties matching the indexes of the child objects it references, as well as a redundant "item" method used to retrieve those same child objects, and a "length" property saying how many child objects there were.

    (Strictly speaking, the interface is called "NodeList" and therefore that is also normally used as the class name of the object. However, depending on what other interfaces are superimposed on top of the same object, it may get a different name in different browsers. It's no big surprise.)



  •  If you've been doing tons of JS for years, you're not good at it. If you were, you would have probably encountered prototype by now. See prototype's implementation of getElementsByClassName, where it clearly says that

    "As of Prototype 1.6, document.getElementsByClassName has been deprecated since native implementations return a NodeList rather than an Array. Please use $$ or Element#select instead."

    Dude, it's all over the web! TRWTF is you, because you didn't do a bit of digging before considering it a WTF.



  •  Not to add to the fire, but this is the standard DOM API, which is the same accross basically all Languages. All proper dom implementations will return a NodeList. That's the case in Javascript, that's the case in Java (org.w3c.dom.NodeList), that's the case in PHP (DOMNodeList), and that's probably the case in a variety of other languages. So I'm afraid that this is supposed to be common knowledge.



  • Ok, let's say for the sake of argument, that I'm a responsible programmer. And I find out that this thing that looks like an array, and that I've already treated as an array with no problems, doesn't have a .push() method. So I decide to look up what methods it does have.

    You're all saying that it's a complete non-WTF that there's ZERO documentation ANYWHERE that says that a dispHTMLElementCollection is the same thing as a NodeList? That there's ZERO documentation ANYWHERE that tells me what member functions dispHTMLElementCollection does happen to contain? (Unless I've somehow used my psychic powers to find out the above.) You're all saying that it's perfectly acceptable for both IE and Mozilla to have a class used by their browser with zero documentation at all?

    Ok, maybe I am a shitty programmer, I accept that. (I don't use libraries like prototype.js, because our JS is served to external clients, it has to be as small as possible. And since it doesn't make many, if any, DHTML manipulations, a library like prototype.js would be completely wasted.)

    But none of you think it wouldn't be a better world if Mozilla and Microsoft just put a page up that said, "Oh BTW this thing is a DOM NodeList, here's a link."?

    Bah.



  • @LordOfThePigs said:

     Not to add to the fire, but this is the standard DOM API, which is the same accross basically all Languages. All proper dom implementations will return a NodeList. That's the case in Javascript, that's the case in Java (org.w3c.dom.NodeList), that's the case in PHP (DOMNodeList), and that's probably the case in a variety of other languages. So I'm afraid that this is supposed to be common knowledge.

     

    How am I supposed to gain the "common knowledge" with no documentation? That's the WTF!

    So to summarize, the real WTF is:

    1) Programmers who expect every publically-accessible class in their programming environment to be documented.

    2) Javascript programmers who have never dug deeply into the prototype.js documentation for getElementsByClassName, even ones who don't use prototype.js.

    3) Javascript programmers who haven't somehow connected the existence of NodeList in Java and PHP to dispHTMLElementCollection in IE and Firefox. Even ones who don't use Java or PHP.

    I guess by the standards of the mob here, I am indeed the real WTF.



  • @blakeyrat said:

    @LordOfThePigs said:
    Not to add to the fire, but this is the standard DOM API, which is the same accross basically all Languages. All proper dom implementations will return a NodeList. That's the case in Javascript, that's the case in Java (org.w3c.dom.NodeList), that's the case in PHP (DOMNodeList), and that's probably the case in a variety of other languages. So I'm afraid that this is supposed to be common knowledge.

    How am I supposed to gain the "common knowledge" with no documentation? That's the WTF!

    Interface HTMLDocument from Document Object Model (DOM) Level 2 HTML Specification, Version 1.0, W3C Recommendation 09 January 2003:

    getElementsByName
    With [HTML 4.01] documents, this method returns the (possibly empty) collection of elements whose name value is given by elementName. In [XHTML 1.0] documents, this methods only return the (possibly empty) collection of form controls with matching name. This method is case sensitive.
    Parameters
    elementName of type DOMString
    The name attribute value for an element.
    Return Value

    NodeList

    The matching elements.

    No Exceptions

    Would you look at that: non-existing documentation.

    @blakeyrat said:

    I guess by the standards of the mob here, I am indeed the real WTF.

    Yes. You should be the real WTF by any standards, considering you neglected to read the bloody DOM Level 2 specification.



  • Oh, let me add to my list:

    * Instead of looking up the actual class I wanted information on, I should have looked up something entirely different and then made the assumption that the class name listed in the DOM documentation was, in fact, the same thing as the class name I was actually seeing in the browser.



  • @blakeyrat said:

    You're all saying that it's a complete non-WTF that there's ZERO documentation ANYWHERE that says that a dispHTMLElementCollection is the same thing as a NodeList?

    We're saying it's a WTF that you go looking on the MSDN site for a description of an object that is created by DOM, and defined in the DOM specification. I don't consider you a bad programmer for this, but simply uninformed. Look in the DOM specs for the DOM APIs, not inside MSDN (which only documents IE's broken DOM support, not the standard). I know you looked in the DOM spec, but it's amazing that all you did was look for a class name, instead of looking for the name of the method you were calling, and seeing what it returned. A stated class name does not necessarily directly map to the DOM interface you are looking for - remember this for future reference, since multiple interfaces can apply to the same class.

    Imagine if you tried to get the class name of the Document object, and expected it to list all the interfaces it implements - in standards compliant browsers such as Opera, Safari/Chrome, Konqueror, Mozilla/Firefox, this would begin with: Document DocumentView DocumentEvent EventTarget DocumentStyle DocumentCSS DocumentTraversal DocumentRange HTMLDocument XPathEvaluator, etc. etc. and many many many more. The toString for each such object would become insanely long if it were to list all these things. You just need to learn to read the DOM specs, and use them to work out what DOM methods will return.

    FWIW, there is a logical reason for it to be a NodeList, not an array - quite apart from the fact that DOM is designed to be used in a OO environment with no array support. The returned object is "live". Say for example that you use getElementsByTagName to retrieve all paragraph elements on the page, and assign the returned object to a variable "foo". Then some time later, your script adds another paragraph to the document. The "foo" object is now updated already, to contain the new reference. That could not be done with a regular array, since push/pop/etc would all break it, by trying to write to something that the script environment is also writing to.

    That functionality is immensely useful in many cases, meaning you don't have to keep calling getElementsByTagName for the same things over and over again; the old object will already contain the updates. However, it can be a gotcha if you make a loop which adds an extra paragraph for each paragraph it finds in the collection, because it will never end.



  • Look, thanks for the message, and for not being as much an a-hole as some of the others on this board, but none of the stuff you just wrote, *none* of it, excuses Microsoft or Mozilla from having a completely undocumented class (or interface, or whatever term you want to use.) Even if their documentation had just pointed to NodeList, I'd be perfectly fine with that. But nothing? No excuse.

    I don't even understand how you can dismiss that as if it's completely unimportant. It's like there's some kind of web developer Stockholm Syndrome where you're so used to web standards being crap, it doesn't even bother you anymore.

    Can you imagine the outcry if there were an undocumented publically-accessible class in the .net framework? Or in the Win32 API?

    Anyway, all I've really learned from this is "never post to Daily WTF."



  • @blakeyrat said:

    Can you imagine the outcry if there were an undocumented publically-accessible class in the .net framework? Or in the Win32 API?

     

    Wait... undocumented win api call? No way! http://nibuthomas.com/category/undocumented-winapi/

    If undocumented features surprise you, you're not programming long enough.



  • @blakeyrat said:

    Look, thanks for the message, and for not being as much an a-hole as some of the others on this board, but none of the stuff you just wrote, *none* of it, excuses Microsoft or Mozilla from having a completely undocumented class (or interface, or whatever term you want to use.) Even if their documentation had just pointed to NodeList, I'd be perfectly fine with that. But nothing? No excuse.

    You shouldn't care what the actual type of the returned object is. All you should care about is that the DOM specification guarantees that it is a subclass of the NodeList type (or implements the NodeList interface, whatever your fancy).

    Querying for the name of the NodeList class belonging to the DOM API in Javascript and complaining that it isn't a simple array, is like using reflection in .NET to break open an IList and complaining that it is a LazilyLoadedCollectionOfInt32 when you thought it should've been List<int>...



  •  @blakeyrat said:

    [...] excuses Microsoft or Mozilla from having a completely undocumented class (or interface, or whatever term you want to use.) Even if their documentation had just pointed to NodeList, I'd be perfectly fine with that. But nothing? No excuse!

    https://developer.mozilla.org/en/gecko_dom_reference

    No documentation? No reference to NodeList? Your google-fu is lacking.



  • @blakeyrat said:

    Can you imagine the outcry if there were an undocumented publically-accessible class in the .net framework? Or in the Win32 API?
    The thing is, that dispHTMLSomethingOrWhatever class isn't really "public" in the usual sense of the word — it's Microsoft's private implementation of the public NodeList interface.  The .getElementsByTagName method is defined to return a NodeList.  NodeList is an interface.  A particular vendor's implementation of that method is completely free to return you an orange, as long as the orange implements the standard NodeList interface.  Heck, it could return a different kind of object every time you call it, as long as all those objects implement NodeList.

    Of course, it would've been nice of Microsoft to put something on the web saying that this dispHTMLElementCollection thingy is their implementation of NodeList, just because someone was bound to come across the name and search for it eventually.  But that doesn't change the fact that what you were doing amounted to peeking under the hood.  Interfaces like NodeList are supposed to be black boxes, for vendors to implement as they will — that's the whole point of having an interface.  If you insist on peeking into the black box, don't be surprised if you find something ugly inside.



  • @blakeyrat said:

    Oh, let me add to my list:

    * Instead of looking up the actual class I wanted information on, I should have looked up something entirely different and then made the assumption that the class name listed in the DOM documentation was, in fact, the same thing as the class name I was actually seeing in the browser.

    The real WTF is that just about all programmers depend upon decent documentation of their language and tools to be able to write quality code0, yet never1 write it for the tools that they produce.  Most of us have learned that when you need docs for an object returned from a function, docs are far more likely to be found on the function than elsewhere - even if the returned object has a very distinctive class.

    No, I take that back.  The real, honest to $deity WTF is that you and I appear to be the only ones here that understand there's a problem with the documentation here - although it sounds like you assumed the class returned in IE was the same class that was returned elsewhere, and that's kind of a WTF also2.

    0 If you're telling me you've written near flawless, yet still legible code which performs in a reasonable time, and it fully complies with the language in which you wrote it, yet you did not write the language, nor do you have decent documentation on that language, how do you know it complies with the language?  Note that there are many alternatives to complying with a language which do not result in completely non-functional code.  Just because the language's parser accepts the code doesn't mean that it was *supposed* to accept the code.

    1 You write docs for your tools, and object to my characterization?  See my 'just about' qualifier at the beginning of that sentence, bub.  And thanks for being there for me.

    2 I program in Perl, C, C++, various unix shells, and Ruby, Python, or Java if needed.  Closest I've ever come to writing JavaScript code is reviewing a bugfix to some JavaScript code.  So I have no idea about these things, other than what I see in the thread here.  But it sounds like everyone else is saying the return type depends on the environment/browser.



  • @tgape said:

    No, I take that back.  The real, honest to $deity WTF is that you and I appear to be the only ones here that understand there's a problem with the documentation here - although it sounds like you assumed the class returned in IE was the same class that was returned elsewhere, and that's kind of a WTF also.

     

    The OP, who has been a JavaScript programmer for years, said that there was ZERO DOCUMENTATION, which isn't true: https://developer.mozilla.org/En/DOM/Document.getElementsByName explains everytthing very clearly. getElementsByClassName is another story, which wasn't even implemented in IE6... https://developer.mozilla.org/En/DOM/Document.getElementsByClassName does the same. The only WTF that I find here is that normally you'd expect to get an object with the same prototype in all the browsers. Now, I don't know, who do you think should have explained to you that the result has different prototypes? MSDN or the Mozilla documentation?

    All the W3C specs on DOM2 say is that "The DOM also specifies a NodeList interface to handle ordered lists of nodes" which means that you shouldn't really care about what the prototype really is, since only the interface is part of the official documentation It also tells you that the NodeList interface has a way of getting the Nth item and a way to find out its length. What more do you need The only issue I see is that Mozilla's documentation page on NodeList is empty, but, considering how much you paid for Firefox, you might contribute to the documentation yourself.

    What is missing from the documentation? If you're complaining that it doesn't return an array as you wanted, write the W3C and explain it to them.



  • @rohypnol said:

    The only issue I see is that Mozilla's documentation page on NodeList is empty

    No it's not. You were just visiting an out-of-date or misplaced URI.



  • @rohypnol said:

    @tgape said:

    No, I take that back.  The real, honest to $deity WTF is that you and I appear to be the only ones here that understand there's a problem with the documentation here - although it sounds like you assumed the class returned in IE was the same class that was returned elsewhere, and that's kind of a WTF also.

     

    The OP, who has been a JavaScript programmer for years, said that there was ZERO DOCUMENTATION, which isn't true: https://developer.mozilla.org/En/DOM/Document.getElementsByName explains everytthing very clearly.

    Thank you for reinforcing my point.  Documentation should exist both for the functions which return objects of a particular class as well as for the class itself.  Pointing out that the former exist does not excuse the class developers from not writing/publishing the latter.

    Now, that having been said, this time I tried actually looking for that class, and well, I found something.  Yes, it's Java, rather than JavaScript, but it is certainly something.

    @rohypnol said:

    The only WTF that I find here is that normally you'd expect to get an object with the same prototype in all the browsers. Now, I don't know, who do you think should have explained to you that the result has different prototypes?

    Never expect to hear a Microsoft apology from me; you'll not get it.  Personally, I'm annoyed at all of the people who continue to prop them up by supporting their crap, now that there are almost viable alternatives.  Admittedly, I don't have room to complain, as I've not really been helping much with the alternatives, either.



  • @tgape said:

    Documentation should exist both for the functions which return objects of a particular class as well as for the class itself.  Pointing out that the former exist does not excuse the class developers from not writing/publishing the latter.

    Sure, but the function in question doesn't return a particular class, but a particular interface. This interface is documented as well, so I don't see a problem. On the other hand, I think that documenting dispHTMLElementCollection would actually be harmful, because it's an implementation detail. Documenting it doesn't give you any benefit, and once you do it, either you're stuck with it for all eternity, or you'll break somebody who relies on it when you change it.



  • @Spectre said:

    @tgape said:
    Documentation should exist both for the functions which return objects of a particular class as well as for the class itself.  Pointing out that the former exist does not excuse the class developers from not writing/publishing the latter.

    Sure, but the function in question doesn't return a particular class, but a particular interface. This interface is documented as well, so I don't see a problem. On the other hand, I think that documenting dispHTMLElementCollection would actually be harmful, because it's an implementation detail. Documenting it doesn't give you any benefit, and once you do it, either you're stuck with it for all eternity, or you'll break somebody who relies on it when you change it.

    The standard function returns an interface.  While I'm not a JavaScript expert, if the language actually allows for returning an interface rather than an object of a class which implements that interface, then ... well, I've been ridiculing the wrong language authors, because that's fricking amazing.  Oddly, however, it seems that the OP checked for what the function actually returned, and it was an object.  That suggests that the actual IE implementation returns an object of a class which implements the standard interface.

    As far as the benefit of documenting the class goes... you're wrong on two counts:

    1. If the class is implementing an interface specified by a standard, it's already constrained to implement that standard interface, and documenting that it does so would not bind it further.
    2. People depend upon undocumented code even more than they depend on documented code: When it isn't documented, they need to work much harder to find out what it does, and when it changes, it's not included on the changelog, so they have no idea that the code needs to be changed until it blows up on them.  When the code is documented, the class maintainers understand more that they need to be careful about making changes to it, and they're much more likely to announce that they've changed it, so that programmers who read the changes documents find out they've changed it before they perform the upgrade, and can therefore update their code before it bombs.

    That having been said, not documenting it does allow the programmer to feel some (completely unjustified) righteous rage after finding out someone has reverse-engineered his programming and then depended upon its behavior.

    Note: if the class simply had been documented as being a subclass of NodeList, it's possible that would have handled the OP's need sufficiently.  The documentation burden here isn't much, which is why it's so ridiculous that it's unmet.  Well, it *was* unmet, but thanks to combined efforts of this thread and Google, it is now sufficiently documented, and the immediate problem is solved.  The longer-term problem, however... do y'all even understand what the longer-term problem is?

    Sigh.



  • Step 1. Vist http://www.google.com

     Step 2. Type in getElementsByTagName

     Step 3. Click "I'm feeling lucky"

    Step 4. Read "<FONT face="Courier New">elements</FONT> is a live NodeList of found elements in the order they appear in the subtree." from the webpage.

     Elsewhere, on the first page of google results, you'll find the MSDN documentation. I'll agree with you there- it's a bit confusing for new programmers who don't understand the difference between arrays and collections.

     You and I have different definations for the term "Undocumented". Just for reference, what did you do to attempt to locate documentation? Did you use any search engines? What terms did you use?



  • @cdosrun said:

     You and I have different definations for the term "Undocumented". Just for reference, what did you do to attempt to locate documentation? Did you use any search engines? What terms did you use?
     

    Step 1. Visit http://www.google.com

    Step 2. Type in the name of the thing I'm actually looking for: dispHTMLElementCollection

    Step 3. Click "Search."

    Step 4. Notice how, except for this very thread and my blog posting, none of the search results say: "dispHTMLElementCollection is actually a DOM2 NodeList." Even fewer relevant results if you add the language you're looking for it in, "Javascript"

    The only real WTF here is that, unlike most people here apparently, when I'm trying to find what X is, I actually search for X. Why would I search for a function when I'm trying to find a list of members to a class? And why, having looked up the function, would I assume that a NodeList and a dispHTMLElementCollection are actually the same thing, when there's absolutely no indication that that's the case?

    Hell, for all I know, dispHTMLElementCollection still could potentially have more methods than NodeList. Since it's undocumented, there's no way to be sure.



  • @blakeyrat said:

    Ok, let's say for the sake of argument, that I'm a responsible programmer. And I find out that this thing that looks like an array, and that I've already treated as an array with no problems, doesn't have a .push() method. So I decide to look up what methods it does have.

    You're all saying that it's a complete non-WTF that there's ZERO documentation ANYWHERE that says that a dispHTMLElementCollection is the same thing as a NodeList?

    Well, if you'd looked up the documentation for getElementsByTagName, you would have seen it returns a NodeList, and wouldn't have been looking for docs based on the name of one particular browser's implementing class. Not looking up the method documentation in the first place is a WTF, but it's not Microsoft's WTF, nor is it the W3C's wtf. In case you had trouble finding it, the documentation is here. And here. Microsoft's unfortunately just calls it a "collection", but that's neither "array" nor any clue where you got the name dispHTMLElementCollection.

    That there's ZERO documentation ANYWHERE that tells me what member functions dispHTMLElementCollection does happen to contain? (Unless I've somehow used my psychic powers to find out the above.) You're all saying that it's perfectly acceptable for both IE and Mozilla to have a class used by their browser with zero documentation at all?

    Ok, maybe I am a shitty programmer, I accept that. (I don't use libraries like prototype.js, because our JS is served to external clients, it has to be as small as possible. And since it doesn't make many, if any, DHTML manipulations, a library like prototype.js would be completely wasted.)

    But none of you think it wouldn't be a better world if Mozilla and Microsoft just put a page up that said, "Oh BTW this thing is a DOM NodeList, here's a link."?

    Bah.

    Mozilla's isn't even called a dispHTMLElementCollection - it's called an HTMLCollection. Which is documented here.



  • @blakeyrat said:

    Hell, for all I know, dispHTMLElementCollection still could potentially have more methods than NodeList. Since it's undocumented, there's no way to be sure.

    But you can't count on those methods being in the object returned by getElementsByTagName. Which is why it's a good thing that (if there are any) they're not documented. Because if there were, people would use them.



  • Judging by his blog entry, I don't think the OP understands OO and the difference between an interface, a class conforming to an interface, and the fact that multiple classes can have the same interface. I think he needs to do a little more studying of the topic...

     

    EDIT

    To quote his blog: "To them, it’s my own fault that I couldn’t tell with only my mind that a dispHTMLElementCollection is actually the same thing as a NodeList as documented in the DOM2 standards."

    dispHTMLElementCollection is an instance of NodeList, but a NodeList and dispHTMLElementCollection are NOT the same thing!



  • @blakeyrat said:

    The only real WTF here is that, unlike most people here apparently, when I'm trying to find what X is, I actually search for X.

     

    You're not looking for dispHTMLElementCollection, you are trying to learn how to use document.getElementsByTagName. Also, you should check into DOM and Javascript a bit more, and collections in general. This will explain why dispHTMLElementCollection is irrelevant to the problem you're experiancing, and help you avoid problems in the future. Also, you'll understand why no one bothered to document this.

     Remember, if you use a tool you're unfamiliar with, and get a result you don't understand, check the documentation on the tool, not the result. You don't search for "broken bones" to figure out how to use a hammer without smashing your thumb.



  • Blakeyrat, and tgape

    Documentation is a kind of contract between API provider and the developer. It describes an Application Programming Interface. It guarantees externally observable behavior. It's not supposed to describe or guarantee any implementation details (internal behavior). In one IE version it could be one class, in another minor version it could change to another, it can get or lose its own internal functions, and you should not be giving a blakey rat's ass about that. If some functions and classes are undocumented, it's because they're not the part of the contract. There is no guarantee about them. And you should not be using them.



  •  @cdosrun said:

    You're not looking for dispHTMLElementCollection, you are trying to learn how to use document.getElementsByTagName.

    No, I was actually looking for dispHTMLElementCollection, since that's what the debugger said I had and I wanted to find out what member functions it had.

    But I give up. I wash my hands of the whole thing. Go ahead, pile on about how much I suck, how I don't understand anything I'm doing, hell I'm practically going full-retard. If your expectations are so low that you it doesn't bother you that hours of my time was wasted because some implementor didn't write a single sentence in their documentation, more power to you. It's my own mistake for not realizing all programmers had to be psychic, and that Google is better-used to search for things unrelated to the things you want to actually find.



  • @blakeyrat said:

    Go ahead, pile on about how much I suck, how I don't understand anything I'm doing, hell I'm practically going full-retard

    I never said any of those things. I pointed out where some of the holes in your knowledge were, pointed out why you were searching for the wrong thing (and a simple rule for how to tell), and gave you a list of suggested reading if you want to become a JavaScript programmer. I carefully did not make fun of you for pretending to already be one. I did not recommend a basic javascript turtorial for you, although it would have help immensely.

     Most everyone else here seems to have done the same.

    @blakeyrat said:

    that hours of my time [were] wasted

     Yeah, if you don't know the basics, that can happen. It's called learning.

     Honestly, this is about the most friendly I've seen people in a long time. Be glad you only got nice responses so far.

     

    Or, you could bury your head in the sand, complain to yourself about those mean old people who don't understand you and how you're so much smarter then they are and are right, by golly! In which case, I look forward to seeing your code featured on this site.


  • ♿ (Parody)

    @blakeyrat said:

    No, I was actually looking for dispHTMLElementCollection, since that's what the debugger said I had and I wanted to find out what member functions it had.
    Yes, and you blindly forged ahead, rather than taking the drastic step of looking up the documentation for the method that returned this object to you.  We all do stupid things like this, but when we finally have the epiphany that's been staring us in the face, we do a facepalm and move on, hopefully a little wiser.  That would be the right thing to do.  Writing a blog post and ranting here, trying to deflect your WTF moment on someone else just amuses the rest of us by being TRWTF yourself.

    @blakeyrat said:

    If your expectations are so low that you it doesn't bother you that hours of my time was wasted because some implementor didn't write a single sentence in their documentation, more power to you.
    No, we're amused because you had such a difficult time finding the answer that was clearly documented, and linked to multiple times.  The schaudenfreude is particularly good, because you lead your post with a statement about your extensive experience with javascript. As was pointed out above, you really seem to have no clue about the difference between an interface and a class. This site thrives on people who refuse to learn from their mistakes. 

    Thanks for keeping the WTF spirit alive.



  • @alegr said:

    Documentation is a kind of contract between API provider and the developer. It describes an Application Programming Interface. It guarantees externally observable behavior.

    I have not asked for anything else.  I hadn't seen Blakeyrat ask for something else until after my last post.

    @tgape said:

    Note: if the class simply had been documented as being a subclass of NodeList, it's possible that would have handled the OP's need sufficiently. The documentation burden here isn't much, which is why it's so ridiculous that it's unmet.

    In fact, I'm now convinced this is exactly what the documentation should've said: This is an implementation of NodeList.

    I stand by my claim that there should be some documentation for any object that a user may be given, even if it's just to point out what interface the object implements.  Blakeyrat's method of documentation hunting *should* work.

    That having been said, blakeyrat's a WTF.  Not only does he seem to want to trust Microsoft's docs over anyone else's, he *wants* to use any proprietary extensions Microsoft has provided.  He is, in fact, complaining that Microsoft has not allowed him to hobble himself in this manner, divesting himself of a significant and growing percentage of the web user market.  For what it's worth, I strongly suspect Microsoft hasn't facilitated his foolishness simply because they have court orders telling them to not pull those kinds of tricks - one in the US, one in the EU.



  • @tgape said:

    That having been said, blakeyrat's a WTF.  Not only does he seem to want to trust Microsoft's docs over anyone else's, he *wants* to use any proprietary extensions Microsoft has provided.  He is, in fact, complaining that Microsoft has not allowed him to hobble himself in this manner, divesting himself of a significant and growing percentage of the web user market.  For what it's worth, I strongly suspect Microsoft hasn't facilitated his foolishness simply because they have court orders telling them to not pull those kinds of tricks - one in the US, one in the EU.
     

    Yah. It couldn't possibly be because I saw the type while using Microsoft's debugger in Microsoft's web browser, and thus looked to Microsoft's documentation for the explanation. Or that Firefox's debugger (at least Firebug, the one I was using) doesn't actually show any type at all for that variable.

    The point I was trying to make above was that since dispHTMLElementCollection is not documented at all, it's not even documented that it's an implementation of NodeList, it could have any variety of member functions. Everybody else on this forum is just assuming it's an interface to NodeList-- how do you know? It's not documented to be one! It could very well be a class, for all you know-- you're just making the assumption that a NodeList and a dispHTMLElementCollection are the same thing, but there's nothing in any of the links in this thread that states that's the case.

    (There are things that states a NodeList is returned by "getElementsByTagName", but nothing that states that a dispHTMLElementCollection is an interface, or a NodeList.)


  • ♿ (Parody)

    @blakeyrat said:

    ...still doesn't get it...
    You don't happen to have some interesting stones, do you?



  • Until it's documented as being an interface to NodeList, it could be anything as far as I'm concerned. Everybody here is just blithely assuming it is, and I'm sure everybody here is right: it is an interface to NodeList. But that has nothing to do with the WTF: the WTF is that it's undocumented by the authority responsible for documenting it. Since nobody has found the documentation page, I'm going to go ahead and declare that to be a fact.

    What part of "it" don't I get? The only thing I'm doing that you're not is making an assumption. I don't like assumptions in programming.



  • @blakeyrat said:

    Yah. It couldn't possibly be because I saw the type while using Microsoft's debugger in Microsoft's web browser, and thus looked to Microsoft's documentation for the explanation. Or that Firefox's debugger (at least Firebug, the one I was using) doesn't actually show any type at all for that variable.

    Sure, the debugger tells you "Here's a dispHTMLElementCollection", it's natural to look for the documentation of that. And if there's really none, that's a WTF, I'm with you and [b]tgape[/b] there.

    But

    The natural next step is then to ask yourself "where did that come from?", and then lookup the documentation of document.getElementsByTagName or whatever produced it. There you'll find that it returns a NodeList, which you can then look up.

    So the natural route leads quickly to the knowledge that, whatever dispHTMLElementCollection is in detail, it ought to be a class implementing the NodeList interface, which gives you all necessary information.

    Your careful avoidance of the natural route is what earns you a moderate bashing here.

    @blakeyrat said:

    The point I was trying to make above was that since dispHTMLElementCollection is not documented at all, it's not even documented that it's an implementation of NodeList, it could have any variety of member functions. Everybody else on this forum is just assuming it's an interface to NodeList-- how do you know? It's not documented to be one! It could very well be a class, for all you know-- you're just making the assumption that a [b]NodeList and a dispHTMLElementCollection are the same thing[/b], but there's nothing in any of the links in this thread that states that's the case.

    Nobody but you assumes they're the same thing. It's been stated here several times that dispHTMLElementCollection is a class [i]implementing[/i] the NodeList interface. There can be any number of classes implementing that interface and each of them may have additional methods. But you shouldn't use any of the additional methods if you want your code to be portable because each browser may choose to return a different class from getElementsByTagName.

    @blakeyrat said:

    (There are things that states a NodeList is returned by "getElementsByTagName", but nothing that states that a dispHTMLElementCollection is an interface, or a NodeList.)

     

    Standard says getElementsByTagName returns a NodeList.

    Debugger says it returned a dispHTMLElementCollection.

    Conclusion: Unless Microsoft broke the standard (not unheard of, granted), dispHTMLElementCollection is a class implementing the NodeList interface.

    What's so difficult about that?


  • ♿ (Parody)

    @blakeyrat said:

    Until it's documented as being an interface to NodeList, it could be anything as far as I'm concerned.
    It's the return value from a method who's return value is documented as something that implements the NodeList interface. How could it be anything else?  Why does it matter what the name of the implementing class is?  All that you're supposed to care about is that it implements NodeList.  If you found that it didn't behave like something that implemented the NodeList interface, then you'd have found a WTF.

    @blakeyrat said:

    What part of "it" don't I get? The only thing I'm doing that you're not is making an assumption. I don't like assumptions in programming.
    There is no assumption here, except that the documentation is correct.  There's no other reasonable assumtion to make, especially with closed source software, at least until there is evidence that the documentation is not correct.  Which neither you (nor anyone else) have never alleged.

    You've latched onto an implementation detail that a debugger allowed you to see, and are trying to find some documentation on what you saw, rather than relying on the (correct!) documentation that exists, and which has been linked to in this thread several times.  

     



  • Your explanation is very sensible and logical and I agree with it 100%, BUT it still doesn't change (or excuse) the fact that dispHTMLElementCollection is undocumented.

    You're just justifying the lack of documentation by chiding me, saying "you *should* have known that, duh." Why are you defending lack of documentation? Isn't lack of documentation in a API generally something considered a WTF? That's seriously where I'm lost here-- I have something that (to me) is a clear WTF, and everybody else thinks it's not because if you search for a few related terms, and piece the clues together, you can figure out what it is to some limited extent. That's not programming, that's playing Clue.

    The amount of verbiage on this site defending the WTF of an undocumented "thing" (whether it be a class, interface, equivalence, widget, whatever) seen in a debugger just shocks and amazes me. Anything the debugger shows me should show up in documentation, period. You're not going to change my mind by giving me pieced together chains of logic. (And so, please, stop doing so, it's been posted like a dozen times already.)



  • @blakeyrat said:

    You're just justifying the lack of documentation by chiding me, saying "you *should* have known that, duh." Why are you defending lack of documentation? Isn't lack of documentation in a API generally something considered a WTF?
      The documentation says that a NodeList will be returned.  The lack of documentation on the specific class that your implementation returned is not a WTF.  The class isn't documented because it doesn't matter.  There are no guarantees that any functionality will or won't work, except that it'll be a NodeList, as has been mentioned over and over.

    @blakeyrat said:

    That's seriously where I'm lost here-- I have something that (to me) is a clear WTF, and everybody else thinks it's not
    Nobody else is having this problem.  That must mean that nobody else has successfully used Javascript, right?  Because if you can't figure it out by copying a word into Google, it's a WTF.

    @blakeyrat said:

    because if you search for a few related terms, and piece the clues together, you can figure out what it is to some limited extent. That's not programming, that's playing Clue.
    "Related terms"?  "Piece the clues together"?  More like "you read the documentation for the function you're using and discover that it returns a NodeList.  Then you use it as a NodeList and never have any problems."  This is exactly like playing Clue, provided that you don't read the directions in Clue, either.

     @blakeyrat said:

    The amount of verbiage on this site defending the WTF of an undocumented "thing" (whether it be a class, interface, equivalence, widget, whatever) seen in a debugger just shocks and amazes me. Anything the debugger shows me should show up in documentation, period.
      Why?  Because it has a name?  It's not documented because you shouldn't be relying on it.  What it can or can't do isn't guaranteed.  Hell, they won't even guarantee that you'll always get that same class.  If it's undocumented, it is so for a reason.



  • Where did you first hear of getElementsByTagName? How did you figure out what information to give it, and why did you expect it to return information you would find usuable?

    Did you just see it in someone elses code, and try to cut and paste it into your own that does something similiar?



  • @bstorer said:

    There are no guarantees that any functionality will or won't work, except that it'll be a NodeList, as has been mentioned over and over.

    @bstorer said:

    It's not documented because you shouldn't be relying on it.

    So I can rely on it being a NodeList, but I can't rely on it being anything at all in particular because it's not documented. Thanks for clearing that up.

    The point is, as I've stated a dozen times and people seem to keep ignoring: I don't know that it's a NodeList, because it's undocumented.



  • @blakeyrat said:

    @bstorer said:

    There are no guarantees that any functionality will or won't work, except that it'll be a NodeList, as has been mentioned over and over.

    @bstorer said:

    It's not documented because you shouldn't be relying on it.

    So I can rely on it being a NodeList, but I can't rely on it being anything at all in particular because it's not documented. Thanks for clearing that up.

    Now you're either being intentionally obtuse or you have a brain malfunction that leaves you incapable of rational thought.  I'm leaning towards the second one.@blakeyrat said:
    The point is, as I've stated a dozen times and people seem to keep ignoring: I don't know that it's a NodeList, because it's undocumented.
    Because you didn't read the documentation for the function you're using.  Why is that anyone else's fault but your own?



  • @blakeyrat said:

    @bstorer said:

    There are no guarantees that any functionality will or won't work, except that it'll be a NodeList, as has been mentioned over and over.

    @bstorer said:

    It's not documented because you shouldn't be relying on it.

    So I can rely on it being a NodeList, but I can't rely on it being anything at all in particular because it's not documented. Thanks for clearing that up.

    The point is, as I've stated a dozen times and people seem to keep ignoring: I don't know that it's a NodeList, because it's undocumented.

     

    Yes, you know now! If you're telling me you still don't know it's a NodeList, go jump off a cliff. Please, quit wasting bandwidth and oxygen. Previous posts have clearly mentioned that NodeList is an interface and the documentations state that the functions return an object that supports some prototype which is the equivalent of the NodeList interface in JavaScript. Read everything again. Carefully. If you don't know how to read, I'm sorry, but there's not much we can do for you.



  •  @bstorer said:

    Because you didn't read the documentation for the function you're using.

    The documentation says it returns a NodeList. What I'm seeing is not a NodeList. There is no documentation that states that a dispHTMLElementCollection is a NodeList.



  • @blakeyrat said:

    The documentation says it returns a NodeList. What I'm seeing is not a NodeList. There is no documentation that states that a dispHTMLElementCollection is a NodeList.

     

     

    I mean this respectfully, but I really feel as though you need to read more about interfaces, polymorphism, their role in implementation hiding, and the purpose of implementation/type hiding, because I don't feel you are grasping the concept. I think this will help you avoid such confusions in the long run, and will certainly help you as a developer. If you ever work with a heavily object-oriented language, it is essential that you understand these concepts to their fullest, as this is one of the very cornerstones of OO.



  •  And when I finish studying that, the documentation will miraculously appear?


  • ♿ (Parody)

    @blakeyrat said:

     And when I finish studying that, the documentation will miraculously appear?
    In a sense, because then you'll know how to read the documentation that already exists (emphasis mine): @w3.org said:
    The NodeList interface provides the abstraction of an ordered collection of nodes, without defining or constraining how this collection is implemented.



  •  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.



  • @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.

    Look, the problem is either that it's undocumented, or that the debugger is showing me the wrong type. Those are the only two possibilities.

    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's true regardless of my understanding of API design-- in fact I don't see how my understanding of API design has anything whatsoever to do with it.

    If dispHTMLElementCollection is the interface to NodeList, 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'm not trying to be hostile, although I'm obviously failing at communicating the problem in some way.


  • ♿ (Parody)

    @blakeyrat said:

    I'm not trying to be hostile, although I'm obviously failing at communicating the problem in some way.
    No, you're failing to understand why you're wrong.  For example:

    @blakeyrat said:

    Look, the problem is either that it's undocumented, or that the debugger is showing me the wrong type.
    Many people have pointed out the third alternative, which is that you don't understand the documentation and what its implications are.


Log in to reply