COMMUNITY

Confusing nomenclature and documentation for js.html.svg.SVGElement and js.html.svg.Element

haxe-js
(Brennan Young) #1

Struggling to make sense of a failing cast for more than a day, we boiled it down to confusing Haxe nomenclature and documentation.

The problem is:

Haxe’s js.html.svg.SVGElement maps to w3’s SVGSVGElement (marked up as <svg>).
…but…
W3’s SVGElement superclass is known to Haxe as js.html.svg.Element.

This is not at all easy to grasp, especially when working with SVG inlined in HTML, and wondering why nodes from nodelists aren’t casting properly.

Worse, in the svg API jumptable, there is a hyperlink from the brief text about Element to SVGElement.html which must be a mistake. Evidently someone else got confused about the names too. (Please fix this!)

What is the rationale for this deviation from the w3 identifier. It’s very confusing when the names for two different, but closely-related classes are so very similar (actually identical, in their non-namespaced form). Could Haxe’s SVG lib not conform to the standard w3c nomenclature?

(Andreas Mokros) #2

Standard w3c is SVGElement (for the general Element) and SVGSVGElement (for the actual <svg>) as you already pointed out. I don’t see how this is less confusing (apart from being the defined standard). I guess the idea for the haxe mapping was to put the first SVG from the name into the path (which is sort of consistent at least).

But I agree that the whole different class mapping under js.html can be confusing, my favorite being:
Element -> js.html.DOMElement
HTMLElement ->js.html.Element

(Brennan Young) #3

Yes that’s (DOMElement vs. Element) is quite a horror, too. An almost identical problem. I still have the teeth marks after being bitten by that.

The standard nomenclature would be less confusing, not just because it’s standard, but also because then we would not be reusing one of the standard names for something quite different in haxe.

I mean, one of the vaunted advantages of strict typing is to save time on ‘foolish’ type errors, but this time saving is certainly compromised, or even negated when the type names borrowed from the standard APIs are applied inconsistently, or swapped around.

It also adds cognitive load if you are (say) relying on the spec (or even something like MDN, which has labeled diagrams of the prototype chain) to find out why things are not working as expected, because you have to continuously ‘translate’ all the similarly-named identifiers back and forth in your head, leaving fewer ‘processor cycles’ for actual problem solving.

So please, Haxe team… If something in a standard target API has an established identifier, use it, verbatim if at all possible. And above all, don’t borrow/reuse another identifier that is used for something else in the same API. Thank you!