From d5271eeae538472f09881496c1a0227456ad486c Mon Sep 17 00:00:00 2001 From: lucasstarsz Date: Sat, 3 Jul 2021 21:56:28 -0400 Subject: [PATCH] (#10, #32) Added missing documentation --- .../tech/fastj/graphics/game/Polygon2D.java | 58 ++++++++++++++++--- .../fastj/graphics/game/Polygon2DBuilder.java | 35 +++++++++++ .../graphics/util/gradients/Gradients.java | 8 +++ .../util/gradients/LinearGradientBuilder.java | 28 +++++++-- 4 files changed, 114 insertions(+), 15 deletions(-) diff --git a/src/main/java/tech/fastj/graphics/game/Polygon2D.java b/src/main/java/tech/fastj/graphics/game/Polygon2D.java index 62e14aab..7d908878 100644 --- a/src/main/java/tech/fastj/graphics/game/Polygon2D.java +++ b/src/main/java/tech/fastj/graphics/game/Polygon2D.java @@ -123,7 +123,7 @@ public static Polygon2D fromPoints(Pointf[] points) { } /** - * Gets the original points that were set for this polygon. + * Gets the polygon's original point set. * * @return The original set of points for this polygon, as a {@code Pointf[]}. */ @@ -132,7 +132,7 @@ public Pointf[] getOriginalPoints() { } /** - * Gets the paint for this polygon. + * Gets the polygon's fill paint. * * @return The {@code Paint} set for this polygon. */ @@ -140,45 +140,85 @@ public Paint getFill() { return fillPaint; } + /** + * Gets the polygon's outline color. + * + * @return The polygon's outline {@code Color}. + */ public Color getOutlineColor() { return outlineColor; } + /** + * Gets the polygon's outline stroke. + * + * @return The polygon's outline {@code BasicStroke}. + */ public BasicStroke getOutlineStroke() { return outlineStroke; } + /** + * Gets the polygon's render style. + * + * @return The polygon's {@code RenderStyle}. + */ public RenderStyle getRenderStyle() { return renderStyle; } /** - * Sets the paint for this polygon. + * Sets the polygon's fill paint. * - * @param newPaint The {@code Paint} to be used for the polygon. - * @return This instance of the {@code Polygon2D}, for method chaining. + * @param newPaint The fill {@code Paint} to be used for the polygon. + * @return The polygon instance, for method chaining. */ public Polygon2D setFill(Paint newPaint) { fillPaint = Objects.requireNonNull(newPaint); return this; } + /** + * Sets the polygon's outline color. + * + * @param newOutlineColor The outline {@code Color} to be used for the polygon. + * @return The polygon instance, for method chaining. + */ public Polygon2D setOutlineColor(Color newOutlineColor) { outlineColor = newOutlineColor; return this; } - public Polygon2D setOutlineStroke(BasicStroke newStroke) { - outlineStroke = newStroke; + /** + * Sets the polygon's outline stroke. + * + * @param newOutlineStroke The outline {@code BasicStroke} to be used for the polygon. + * @return The polygon instance, for method chaining. + */ + public Polygon2D setOutlineStroke(BasicStroke newOutlineStroke) { + outlineStroke = newOutlineStroke; return this; } - public Polygon2D setOutline(BasicStroke newStroke, Color newOutlineColor) { - outlineStroke = newStroke; + /** + * Sets the polygon's outline stroke and color. + * + * @param newOutlineStroke The outline {@code BasicStroke} to be used for the polygon. + * @param newOutlineColor The outline {@code Color} to be used for the polygon. + * @return The polygon instance, for method chaining. + */ + public Polygon2D setOutline(BasicStroke newOutlineStroke, Color newOutlineColor) { + outlineStroke = newOutlineStroke; outlineColor = newOutlineColor; return this; } + /** + * Sets the polygon's render style. + * + * @param newRenderStyle The {@code RenderStyle} to be used for the polygon. + * @return The polygon instance, for method chaining. + */ public Polygon2D setRenderStyle(RenderStyle newRenderStyle) { renderStyle = newRenderStyle; return this; diff --git a/src/main/java/tech/fastj/graphics/game/Polygon2DBuilder.java b/src/main/java/tech/fastj/graphics/game/Polygon2DBuilder.java index eb6efedb..70aa821a 100644 --- a/src/main/java/tech/fastj/graphics/game/Polygon2DBuilder.java +++ b/src/main/java/tech/fastj/graphics/game/Polygon2DBuilder.java @@ -9,6 +9,7 @@ import java.awt.Paint; import java.util.Objects; +/** A builder class for creating {@link Polygon2D} objects. */ public class Polygon2DBuilder { private final Pointf[] points; @@ -23,23 +24,52 @@ public class Polygon2DBuilder { private float rotation = Transform2D.DefaultRotation; private Pointf scale = Transform2D.DefaultScale.copy(); + /** + * {@code Polygon2DBuilder} constructor, taking in a set of points, a render style, and a {@code shouldRender} + * boolean. + * + * @param points The {@code Pointf} array of mesh points to use for the resulting {@code Polygon2D}. + * @param renderStyle The {@code RenderStyle} to use for the resulting {@code Polygon2D}. + * @param shouldRender The "should render" {@code boolean} to use for the resulting {@code Polygon2D}. + */ Polygon2DBuilder(Pointf[] points, RenderStyle renderStyle, boolean shouldRender) { this.points = Objects.requireNonNull(points, "The array of points must not be null."); this.renderStyle = Objects.requireNonNull(renderStyle, "The render style must not be null."); this.shouldRender = shouldRender; } + /** + * Sets the builder's fill paint value. + * + * @param fillPaint The fill {@code Paint} to be used in the resulting {@code Polygon2D}. + * @return The {@code Polygon2DBuilder}, for method chaining. + */ public Polygon2DBuilder withFill(Paint fillPaint) { this.fillPaint = Objects.requireNonNull(fillPaint, "The fill must not be null."); return this; } + /** + * Sets the builder's outline stroke and outline color values. + * + * @param outlineStroke The outline {@code BasicStroke} to be used in the resulting {@code Polygon2D}. + * @param outlineColor The outline {@code Color} to be used in the resulting {@code Polygon2D}. + * @return The {@code Polygon2DBuilder}, for method chaining. + */ public Polygon2DBuilder withOutline(BasicStroke outlineStroke, Color outlineColor) { this.outlineStroke = Objects.requireNonNull(outlineStroke, "The outline stroke must not be null."); this.outlineColor = Objects.requireNonNull(outlineColor, "The outline color must not be null."); return this; } + /** + * Sets the builder's transformation (translation, rotation, scale) values. + * + * @param translation The translation {@code Pointf} to be used in the resulting {@code Polygon2D}. + * @param rotation The rotation {@code float} to be used in the resulting {@code Polygon2D}. + * @param scale The scale {@code Pointf} to be used int he resulting {@code Polygon2D}. + * @return The {@code Polygon2DBuilder}, for method chaining. + */ public Polygon2DBuilder withTransform(Pointf translation, float rotation, Pointf scale) { this.translation = Objects.requireNonNull(translation, "The translation value must not be null."); this.scale = Objects.requireNonNull(scale, "The scale value must not be null."); @@ -50,6 +80,11 @@ public Polygon2DBuilder withTransform(Pointf translation, float rotation, Pointf return this; } + /** + * Creates a new {@link Polygon2D} object, using the data provided by earlier method calls. + * + * @return The resulting {@code Polygon2D}. + */ public Polygon2D build() { return (Polygon2D) new Polygon2D(points) .setOutlineStroke(outlineStroke) diff --git a/src/main/java/tech/fastj/graphics/util/gradients/Gradients.java b/src/main/java/tech/fastj/graphics/util/gradients/Gradients.java index 4eea0ffa..806c59b9 100644 --- a/src/main/java/tech/fastj/graphics/util/gradients/Gradients.java +++ b/src/main/java/tech/fastj/graphics/util/gradients/Gradients.java @@ -28,6 +28,9 @@ public class Gradients { /** * Gets a builder instance for creating a {@link LinearGradientPaint}. * + * @param drawable The {@code Drawable} containing the start and endpoints as its boundaries. + * @param start The {@code Boundary} from which to start the gradient. + * @param end The {@code Boundary} at which to end the gradient. * @return A {@link LinearGradientPaint} builder. */ public static LinearGradientBuilder linearGradient(Drawable drawable, Boundary start, Boundary end) { @@ -37,6 +40,8 @@ public static LinearGradientBuilder linearGradient(Drawable drawable, Boundary s /** * Gets a builder instance for creating a {@link LinearGradientPaint}. * + * @param start The {@code Pointf} from which to start the gradient. + * @param end The {@code Pointf} at which to end the gradient. * @return A {@link LinearGradientPaint} builder. */ public static LinearGradientBuilder linearGradient(Pointf start, Pointf end) { @@ -46,6 +51,7 @@ public static LinearGradientBuilder linearGradient(Pointf start, Pointf end) { /** * Gets a builder instance for creating a {@link RadialGradientPaint}. * + * @param drawable The {@code Drawable} defining the centerpoint and radius to build the gradient with. * @return A {@link RadialGradientPaint} builder. */ public static RadialGradientBuilder radialGradient(Drawable drawable) { @@ -55,6 +61,8 @@ public static RadialGradientBuilder radialGradient(Drawable drawable) { /** * Gets a builder instance for creating a {@link RadialGradientPaint}. * + * @param center The {@code Drawable} defining the centerpoint for the gradient. + * @param radius The {@code float} defining the radius for the gradient. * @return A {@link RadialGradientPaint} builder. */ public static RadialGradientBuilder radialGradient(Pointf center, float radius) { diff --git a/src/main/java/tech/fastj/graphics/util/gradients/LinearGradientBuilder.java b/src/main/java/tech/fastj/graphics/util/gradients/LinearGradientBuilder.java index 79458da0..38b49f72 100644 --- a/src/main/java/tech/fastj/graphics/util/gradients/LinearGradientBuilder.java +++ b/src/main/java/tech/fastj/graphics/util/gradients/LinearGradientBuilder.java @@ -17,21 +17,32 @@ public class LinearGradientBuilder implements GradientBuilder { private final Color[] colors; private int count; - /** Initializes a {@code LinearGradientBuilder}'s internals. */ + /** + * Initializes a {@code LinearGradientBuilder}'s internals. + * + * @param drawable The basis for what the {@code start} and {@code end} end positions evaluate to. + * @param start The starting boundary to create the gradient from. + * @param end The ending boundary to create the gradient from. + */ LinearGradientBuilder(Drawable drawable, Boundary start, Boundary end) { colors = new Color[Gradients.MaximumColorCount]; position(drawable, start, end); } - /** Initializes a {@code LinearGradientBuilder}'s internals. */ + /** + * Initializes a {@code LinearGradientBuilder}'s internals. + * + * @param start The {@code Pointf} defining the starting point of the gradient. + * @param end The {@code Pointf} defining the ending point of the gradient. + */ LinearGradientBuilder(Pointf start, Pointf end) { colors = new Color[Gradients.MaximumColorCount]; position(start, end); } /** - * Sets the starting and ending points for the builder, based on the provided {@link Drawable} and {@link Boundary} - * values. + * Sets the starting and ending points for the resulting gradient, based on the provided {@link Drawable} and {@link + * Boundary} values. * * @param drawable The basis for what the {@code start} and {@code end} end positions evaluate to. * @param start The starting boundary to create the gradient from. @@ -45,7 +56,7 @@ private void position(Drawable drawable, Boundary start, Boundary end) { } /** - * Sets the starting and ending points for the builder, based on the provided {@link Pointf} values. + * Sets the starting and ending points for the resulting gradient, based on the provided {@link Pointf} values. * * @param start The {@code Pointf} defining the starting point of the gradient. * @param end The {@code Pointf} defining the ending point of the gradient. @@ -93,7 +104,7 @@ public LinearGradientBuilder withColors(Color... colors) { } /** - * Creates a new {@link LinearGradientPaint} object, using the data provided by other method calls. + * Creates a new {@link LinearGradientPaint} object, using the data provided by earlier method calls. * * @return The resulting {@code LinearGradientPaint}. */ @@ -108,6 +119,8 @@ public LinearGradientPaint build() { /** * Gets a new instance of a {@link LinearGradientBuilder}. * + * @param start The {@code Pointf} defining the starting point of the gradient. + * @param end The {@code Pointf} defining the ending point of the gradient. * @return The {@code LinearGradientBuilder} instance. */ static LinearGradientBuilder builder(Pointf start, Pointf end) { @@ -117,6 +130,9 @@ static LinearGradientBuilder builder(Pointf start, Pointf end) { /** * Gets a new instance of a {@link LinearGradientBuilder}. * + * @param drawable The basis for what the {@code start} and {@code end} end positions evaluate to. + * @param start The starting boundary to create the gradient from. + * @param end The ending boundary to create the gradient from. * @return The {@code LinearGradientBuilder} instance. */ static LinearGradientBuilder builder(Drawable drawable, Boundary start, Boundary end) {