8252547: Correct transformations docs in Node

Reviewed-by: kcr, arapte

Author: nlisker

modules/javafx.graphics/src/main/java/javafx/scene/Node.java

@@ -225,7 +225,7 @@
  * an UnsupportedOperationException being thrown.
  * </p>
  *
- * <h2>String ID</h2>
+ * <h2><a id="StringID">String ID</a></h2>
  * <p>
  * Each node in the scene graph can be given a unique {@link #idProperty id}. This id is
  * much like the "id" attribute of an HTML tag in that it is up to the designer
@@ -235,7 +235,7 @@
  * scene graph. The id can also be used identify nodes for applying styles; see
  * the CSS section below.
  *
- * <h2>Coordinate System</h2>
+ * <h2><a id="CoordinateSystem">Coordinate System</a></h2>
  * <p>
  * The {@code Node} class defines a traditional computer graphics "local"
  * coordinate system in which the {@code x} axis increases to the right and the
@@ -268,7 +268,7 @@
  * important context-specific information about coordinate mapping and how
  * it can affect rendering.
  *
- * <h2>Transformations</h2>
+ * <h2><a id="Transformations">Transformations</a></h2>
  * <p>
  * Any {@code Node} can have transformations applied to it. These include
  * translation, rotation, scaling, or shearing.
@@ -321,11 +321,22 @@
  * A <b>shearing</b> transformation, sometimes called a skew, effectively
  * rotates one axis so that the x and y axes are no longer perpendicular.
  * <p>
- * Multiple transformations may be applied to a node by specifying an ordered
- * chain of transforms.  The order in which the transforms are applied is
- * defined by the ObservableList specified in the {@link #getTransforms transforms} variable.
+ * Multiple transformations may be applied to a node. Custom transforms are applied using the
+ * {@link #getTransforms transforms} list. Predefined transforms are applied using the properties specified below.
+ * The matrices that represent the transforms are multiplied in this order:
+ * <ol>
+ * <li> Layout ({@link #layoutXProperty layoutX}, {@link #layoutYProperty layoutY}) and translate
+ * ({@link #translateXProperty translateX}, {@link #translateYProperty translateY}, {@link #translateZProperty translateZ})</li>
+ * <li> Rotate ({@link #rotateProperty rotate})</li>
+ * <li> Scale ({@link #scaleXProperty scaleX}, {@link #scaleYProperty scaleY}, {@link #scaleZProperty scaleZ})</li>
+ * <li> Transforms list ({@link #getTransforms transforms}) starting from element 0</li>
+ * </ol>
+ * The transforms are applied in the reverse order of the matrix multiplication outlined above: last element of the transforms list
+ * to 0th element, scale, rotate, and layout and translate. By applying the transforms in this order, the bounds in the local
+ * coordinates of the node are transformed to the bounds in the parent coordinate of the node (see the
+ * <a href="#BoundingRectangles">Bounding Rectangles</a> section).
  *
- * <h2>Bounding Rectangles</h2>
+ * <h2><a id="BoundingRectangles">Bounding Rectangles</a></h2>
  * <p>
  * Since every {@code Node} has transformations, every Node's geometric
  * bounding rectangle can be described differently depending on whether
@@ -340,9 +351,7 @@
  * <p>
  * Each {@code Node} also has a read-only {@link #boundsInParentProperty boundsInParent} variable which
  * specifies the bounding rectangle of the {@code Node} after all transformations
- * have been applied, including those set in {@link #getTransforms transforms},
- * {@link #scaleXProperty scaleX}/{@link #scaleYProperty scaleY}, {@link #rotateProperty rotate},
- * {@link #translateXProperty translateX}/{@link #translateYProperty translateY}, and {@link #layoutXProperty layoutX}/{@link #layoutYProperty layoutY}.
+ * have been applied as specified in the <a href="#Transformations">Transformations</a> section.
  * It is called "boundsInParent" because the rectangle will be relative to the
  * parent's coordinate system.  This is the 'visual' bounds of the node.
  * <p>
@@ -380,8 +389,7 @@
  * <p> <img src="doc-files/bounds.png" alt="The rectangles are enclosed by their
  * respective bounds"> </p>
  *
- *
- * <h2>CSS</h2>
+ * <h2><a id="CSS">CSS</a></h2>
  * <p>
  * The {@code Node} class contains {@code id}, {@code styleClass}, and
  * {@code style} variables that are used in styling this node from
@@ -393,6 +401,7 @@
  * For further information about CSS and how to apply CSS styles
  * to nodes, see the <a href="doc-files/cssref.html">CSS Reference
  * Guide</a>.
+ *
  * @since JavaFX 2.0
  */
 @IDProperty("id")
@@ -3388,21 +3397,12 @@ public final Bounds getBoundsInParent() {
     }
 
     /**
-     * The rectangular bounds of this {@code Node} which include its transforms.
-     * {@code boundsInParent} is calculated by
-     * taking the local bounds (defined by {@link #boundsInLocalProperty boundsInLocal}) and applying
-     * the transform created by setting the following additional variables
-     * <ol>
-     * <li>{@link #getTransforms transforms} ObservableList</li>
-     * <li>{@link #scaleXProperty scaleX}, {@link #scaleYProperty scaleY}, {@link #scaleZProperty scaleZ}</li>
-     * <li>{@link #rotateProperty rotate}</li>
-     * <li>{@link #layoutXProperty layoutX}, {@link #layoutYProperty layoutY}</li>
-     * <li>{@link #translateXProperty translateX}, {@link #translateYProperty translateY},
-     * {@link #translateZProperty translateZ}</li>
-     * </ol>
+     * The rectangular bounds of this {@code Node} in the parent coordinate system.
+     * {@code boundsInParent} is calculated by taking the {@linkplain #boundsInLocalProperty local bounds} and applying
+     * the node transforms as specified in the <a href="#Transformations">Transformations</a> section of the class doc.
      * <p>
      * The resulting bounds will be conceptually in the coordinate space of the
-     * {@code Node}'s parent, however the node need not have a parent to calculate
+     * {@code Node}'s parent, however, the node need not have a parent to calculate
      * these bounds.
      * <p>
      * Note that this method does not take the node's visibility into account;
@@ -3418,7 +3418,10 @@ public final Bounds getBoundsInParent() {
      * this variable. For example, the x or y variables of a shape, or
      * {@code translateX}, {@code translateY} should never be bound to
      * {@code boundsInParent} for the purpose of positioning the node.
-     * @return the boundsInParent for this {@code Node}
+     * <p>
+     * See also the <a href="#BoundingRectangles">Bounding Rectangles</a> section.
+     *
+     * @return the {@code boundsInParent} property for this {@code Node}
      */
     public final ReadOnlyObjectProperty<Bounds> boundsInParentProperty() {
         return getMiscProperties().boundsInParentProperty();
@@ -5519,10 +5522,10 @@ public final double getViewOrder() {
      *                                                                         *
      **************************************************************************/
     /**
-     * Defines the ObservableList of {@link javafx.scene.transform.Transform} objects
-     * to be applied to this {@code Node}. This ObservableList of transforms is applied
-     * before {@link #translateXProperty translateX}, {@link #translateYProperty translateY}, {@link #scaleXProperty scaleX}, and
-     * {@link #scaleYProperty scaleY}, {@link #rotateProperty rotate} transforms.
+     * The {@code ObservableList} of custom {@link javafx.scene.transform.Transform}s
+     * to be applied to this {@code Node}. These transforms are applied before the predefined transforms.
+     * <p>
+     * See also the <a href="#Transformations">Transformations</a> section.
      *
      * @return the transforms for this {@code Node}
      * @defaultValue empty