7022931: GradientPaint class spec clarification: 7022931, 7016391, 7017246, 7019386

Reviewed-by: flar

jdk/src/share/classes/java/awt/LinearGradientPaint.java

@@ -57,8 +57,14 @@ import java.beans.ConstructorProperties;
  * </pre>
  *
  * <p>
- * The user may also select what action the {@code LinearGradientPaint}
- * should take when filling color outside the start and end points.
+ * The user may also select what action the {@code LinearGradientPaint} object
+ * takes when it is filling the space outside the start and end points by
+ * setting {@code CycleMethod} to either {@code REFLECTION} or {@code REPEAT}.
+ * The distances between any two colors in any of the reflected or repeated
+ * copies of the gradient are the same as the distance between those same two
+ * colors between the start and end points.
+ * Note that some minor variations in distances may occur due to sampling at
+ * the granularity of a pixel.
  * If no cycle method is specified, {@code NO_CYCLE} will be chosen by
  * default, which means the endpoint colors will be used to fill the
  * remaining area.

jdk/src/share/classes/java/awt/MultipleGradientPaint.java

@@ -286,6 +286,10 @@ public abstract class MultipleGradientPaint implements Paint {
     /**
      * Returns a copy of the transform applied to the gradient.
      *
+     * <p>
+     * Note that if no transform is applied to the gradient
+     * when it is created, the identity transform is used.
+     *
      * @return a copy of the transform applied to the gradient
      */
     public final AffineTransform getTransform() {
@@ -293,10 +297,12 @@ public abstract class MultipleGradientPaint implements Paint {
     }
 
     /**
-     * Returns the transparency mode for this Paint object.
+     * Returns the transparency mode for this {@code Paint} object.
      *
-     * @return an integer value representing the transparency mode for
-     * this Paint object
+     * @return {@code OPAQUE} if all colors used by this
+     *         {@code Paint} object are opaque,
+     *         {@code TRANSLUCENT} if at least one of the
+     *         colors used by this {@code Paint} object is not opaque.
      * @see java.awt.Transparency
      */
     public final int getTransparency() {

jdk/src/share/classes/java/awt/RadialGradientPaint.java

@@ -71,8 +71,24 @@ import java.beans.ConstructorProperties;
  * </pre>
  *
  * <p>
- * The user may also select what action the {@code RadialGradientPaint}
- * should take when filling color outside the bounds of the circle's radius.
+ * The user may also select what action the {@code RadialGradientPaint} object
+ * takes when it is filling the space outside the circle's radius by
+ * setting {@code CycleMethod} to either {@code REFLECTION} or {@code REPEAT}.
+ * The gradient color proportions are equal for any particular line drawn
+ * from the focus point. The following figure shows that the distance AB
+ * is equal to the distance BC, and the distance AD is equal to the distance DE.
+ * <center>
+ * <img src = "doc-files/RadialGradientPaint-3.png">
+ * </center>
+ * If the gradient and graphics rendering transforms are uniformly scaled and
+ * the user sets the focus so that it coincides with the center of the circle,
+ * the gradient color proportions are equal for any line drawn from the center.
+ * The following figure shows the distances AB, BC, AD, and DE. They are all equal.
+ * <center>
+ * <img src = "doc-files/RadialGradientPaint-4.png">
+ * </center>
+ * Note that some minor variations in distances may occur due to sampling at
+ * the granularity of a pixel.
  * If no cycle method is specified, {@code NO_CYCLE} will be chosen by
  * default, which means the the last keyframe color will be used to fill the
  * remaining area.
@@ -604,7 +620,7 @@ public final class RadialGradientPaint extends MultipleGradientPaint {
     }
 
     /**
-     * Returns a copy of the end point of the gradient axis.
+     * Returns a copy of the focus point of the radial gradient.
      *
      * @return a {@code Point2D} object that is a copy of the focus point
      */