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

[Kevin Rushforth]

On Mon, 10 Aug 2020 10:26:50 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

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

It seems best to revert all of the transform changes in this PR and deal with it in 16.

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

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