[jfx15] RFR: 8228570: Add various documentation clarifications [v2]

[Nir Lisker]

On Fri, 7 Aug 2020 14:18:31 GMT, Kevin Rushforth <kcr at openjdk.org> wrote:

>> modules/javafx.graphics/src/main/java/javafx/scene/Node.java line 5523:
>> 
>>> 5522:      * Defines the {@code ObservableList} of {@link Transform} objects to be applied to this {@code Node}. The
>>> transforms in this list 5523:      * are applied in the <i>reverse</i> order of which they are specified as per matrix
>>> multiplication rules. This list of transforms 5524:      * is applied before scaling ({@link #scaleXProperty scaleX},
>>> {@link #scaleYProperty scaleY} and {@link #scaleZProperty scaleZ}),
>> 
>> `The transforms in this list are applied in the <i>reverse</i> order of which they are specified as per matrix
>> multiplication rules`
>> To apply transformations in a specific order their respective matrices should be multiplied in reverse order. So just
>> the order of multiplication is reverse but the transformation are applied in same order as they are added into the
>> `getTransforms()`. I think phrasing it as 'the transforms are applied in reverse order...' would not be accurate and
>> confusing to reader.
>
> In reading the existing doc carefully, it is both wrong and confusing. It has the wrong ordering of transform, scale
> and rotate. It is also confusing given that no distinction is made between matrix multiplication order and the observed
> effect on the geometry of the node. You have fixed the part about it being wrong, but the confusion remains, especially
> since you made a point of saying that the transforms list is applied in the reverse order.  The matrices are multiplied
> in the following order:  1. layoutX/Y + translateX/Y/Z
> 2. rotate
> 3. scale
> 4. transforms[0]
> 5. transforms[1]
> ...
> 
> We need to both list the actual matrix multiplication order, and then describe that the object is transformed from
> object coordinates to local coordinates of the node, to parent coordinated, etc., by first applying the transforms in
> the list in reverse order, then scale, rotate, translate+layout. I don't think that the `transforms` list is the place
> to do that (it belongs in the Transformations section).  This doesn't seem like something we can sort out for JavaFX
> 15, so I would split this out and defer it.

So should I revert all the changes about the transforms and leave it for 16, or do part of it now and part later?
The changes are in the docs for the `Node` class, the `getTransforms()` method and the `boundsInParentProperty()`
method.

-------------

PR: https://git.openjdk.java.net/jfx/pull/276