Ecma262: ES2016 garbled the "Generator Objects Relationships" digram

[allenwb]

When ES2015 Figure 2 was redrafted as ES2016 Figure 2 it was changed in ways that, according to the UML standard, mean that the diagram no longer correctly describes the intended ECMAScript object models. That broken diagram is in the current spec draft as ES2019 Figure 5.

The biggest issue is that the association end labels were all moved to the opposite ends of their association lines. For example:

was changed to:

This is wrong, given if a reader assumes a reasonable convention that an association end label corresponds to the name of a property of a referencing object whose value is the object that is the "value" of the association. According to the UML standard, labels are to be placed near the "value" end rather than the referencing end of the line. As a further explanation , see:

from (https://www.uml-diagrams.org/association.html) or if you're really brave the actual UML strandard.

The interpretation intended by the original ES2015 digram is that generator function object g1 has a property named prototype whose value is the object g1.prototype and does not have a property that allows navigation from g1.prototype to g1. That corresponds to what the normative spec text defines. The revised ES2016 diagram would be interpreted by anyone familiar with UML as saying that the object named g1.prototype has a property named prototype whose value is the generator function object g1 but does not have a property for navigating from g1 to g1.prototype. That is clearly incorrect.

There are other issues, such as even though the association labels were reversed the corresponding navigation arrow heads were not.

I suspect that whoever redrafted the diagram was not actually familiar with UML, was confused by the placement of the association labels, and tried to fix them. That is a pretty plausible error, as the standard label placement seems unintuitive to many people when they are first exposed to UML. However, the reason for using a standard notation is so that readers either already know how to read the notation or can "look it up". Using a arbitrarily modified form of a standard notation is a bad idea because people who know the notation will misread it and those who don't know the notation don't have a place to "look it up" unless you go to the trouble to fully describing how to interpreted the made-up notation.

The diagram needs to be updated so that it reflects the original association label placements from ES2015

[bakkot]

See also #364.

[ljharb]

Is there a standard non-image UML format that would be a better format to store it in, so that future updates are less likely to break things?

[allenwb]

@ljharb The ES2015 diagram was created using the free version of the Astah UML Editor. Since the free version of that editor didn't support generating SVG renderings we used it to create the png version of the diagram. The editable UML source file of that version of the diagram is at https://github.com/tc39/ecma262-6-src/blob/master/6.0-docs/ES%20core%20generator%20objects%20ES6.asta. Also see the accompanying readme.

My recollection is that for ES2016/ECMarkup @bterlson wanted to have a SVG version of the diagram so he found somebody (presumably at Microsoft) to redraft the diagram using some available SVG editor. I assume that is when the UML mistake were made. I would hope that the editable SVG file for that version exists somewhere. I don't know why it isn't in https://github.com/tc39/ecma262/tree/master/img or why the HTML version of the current spec. doesn't render using a svg file.

[ljharb]

I'd like to see us come up with some way to autogenerate an SVG from a more standard format (like the one you linked) - that way once we do fix this diagram, we'll be able to keep it fixed moving forwards.

[erights]

See also https://github.com/tc39/ecma262/issues/1735