From c9a082320d03874cdec4c95c0bad8ce768ad8b5c Mon Sep 17 00:00:00 2001 From: Fokinator Date: Sun, 31 May 2026 22:05:35 +0300 Subject: [PATCH] fix JavaDoc --- src/main/java/net/fokinatorr/sparkle/Lifecycle.java | 2 +- .../fokinatorr/sparkle/audio/io/SoundDecoder.java | 10 +++++----- .../sparkle/event/annotation/EventListener.java | 1 + .../sparkle/event/input/KeyboardEvent.java | 8 ++++---- .../java/net/fokinatorr/sparkle/graphics/ARGB.java | 8 ++++---- .../graphics/font/FilesystemFontProvider.java | 8 ++++---- .../graphics/impl/surface/GLFWToPublicAPI.java | 2 +- .../sparkle/graphics/render/RenderCanvas.java | 12 ++++++------ .../graphics/render/surface/RenderingSurface.java | 2 +- .../graphics/render/surface/WindowSurface.java | 2 +- .../java/net/fokinatorr/sparkle/phys2d/Hitbox2D.java | 1 + .../java/net/fokinatorr/sparkle/phys2d/Point2D.java | 2 +- .../java/net/fokinatorr/sparkle/util/Global.java | 3 ++- .../net/fokinatorr/sparkle/util/TypeReference.java | 2 +- .../java/net/fokinatorr/sparkle/util/WaitUtils.java | 4 ++-- .../fokinatorr/sparkle/variable/ObjectVariable.java | 2 +- 16 files changed, 36 insertions(+), 33 deletions(-) diff --git a/src/main/java/net/fokinatorr/sparkle/Lifecycle.java b/src/main/java/net/fokinatorr/sparkle/Lifecycle.java index a808585..c099e6c 100644 --- a/src/main/java/net/fokinatorr/sparkle/Lifecycle.java +++ b/src/main/java/net/fokinatorr/sparkle/Lifecycle.java @@ -22,7 +22,7 @@ import java.util.Objects; import java.util.ServiceLoader; import java.util.function.Supplier; -import static net.fokinatorr.sparkle.util.WaitUtils.waitFor; +import static net.fokinatorr.sparkle.util.WaitUtils.*; import static org.lwjgl.system.Configuration.DEBUG; import static org.lwjgl.system.Configuration.LIBRARY_PATH; diff --git a/src/main/java/net/fokinatorr/sparkle/audio/io/SoundDecoder.java b/src/main/java/net/fokinatorr/sparkle/audio/io/SoundDecoder.java index 13bb2e0..bb724a2 100644 --- a/src/main/java/net/fokinatorr/sparkle/audio/io/SoundDecoder.java +++ b/src/main/java/net/fokinatorr/sparkle/audio/io/SoundDecoder.java @@ -13,13 +13,13 @@ import java.util.Set; /** * A sound decoder can decode a {@link Path file}, a {@link InputStream stream of bytes}, or a {@link ByteBuffer byte buffer} * into a {@link ParsedSound} (PCM data). - *

Currently supported formats: + *

Currently supported formats: *

+ * *

Note for Scratchers: Unlike Scratch, which supports many formats (including MP3 and WAV), * we currently only support OGG Vorbis. This keeps the core lightweight and focused on free, open formats. - * If you have sounds in other formats that you want to use: + * If you have sounds in other formats that you want to use: *

    *
  1. * Easy way (recommended): convert them to one of the supported formats @@ -33,7 +33,7 @@ import java.util.Set; * * You can get the context using {@link AppContextHolder} utilities. *
  2. - *
+ * * @see ParsedSound */ public interface SoundDecoder { @@ -62,7 +62,7 @@ public interface SoundDecoder { * @return a new parsed sound * @throws IOException if an I/O or parse error occurs * @throws NullPointerException if input stream is {@code null} - * @implNote The default implementation reads all remaining bytes of the + * @implSpec The default implementation reads all remaining bytes of the * input stream into an off-heap buffer, parses them and then frees the buffer. */ default ParsedSound parseStream(InputStream in) throws IOException { diff --git a/src/main/java/net/fokinatorr/sparkle/event/annotation/EventListener.java b/src/main/java/net/fokinatorr/sparkle/event/annotation/EventListener.java index 22aaa0d..37a1789 100644 --- a/src/main/java/net/fokinatorr/sparkle/event/annotation/EventListener.java +++ b/src/main/java/net/fokinatorr/sparkle/event/annotation/EventListener.java @@ -18,6 +18,7 @@ import java.lang.reflect.InaccessibleObjectException; * The return value is ignored and can be of any type. * * + *

*

Note: If you use named modules and a class containing a method annotated with this annotation is not * exported outside the module, or the method and/or class are not public, you should export/open the * containing package (respectively) to module {@code ru.fokinatorr.sparkle.core}, otherwise an {@link InaccessibleObjectException} diff --git a/src/main/java/net/fokinatorr/sparkle/event/input/KeyboardEvent.java b/src/main/java/net/fokinatorr/sparkle/event/input/KeyboardEvent.java index f19fc39..cbbabdf 100644 --- a/src/main/java/net/fokinatorr/sparkle/event/input/KeyboardEvent.java +++ b/src/main/java/net/fokinatorr/sparkle/event/input/KeyboardEvent.java @@ -9,7 +9,7 @@ import java.util.Objects; /** * Base interface for events representing a keyboard event. *

Note for Scratchers: This event is similar to the "when [ v] key pressed" in Scratch. Unfortunately, - * there is no universal event type for every single key. See the JavaDoc of the subinterfaces & implementations + * there is no universal event type for every single key. See the JavaDoc of the subinterfaces & implementations * to see which event type you need. */ public sealed interface KeyboardEvent extends InputEvent @@ -71,13 +71,13 @@ public sealed interface KeyboardEvent extends InputEvent *

          *     // ...
          *     int mod = event.modifiers();
-         *     if ((mod & KeyEvent.MOD_SHIFT) != 0) {
+         *     if ((mod & KeyEvent.MOD_SHIFT) != 0) {
          *         // do something if the Shift key was down
          *     }
-         *     if ((mod & KeyEvent.MOD_NUM_LOCK) != 0) {
+         *     if ((mod & KeyEvent.MOD_NUM_LOCK) != 0) {
          *         // do something if Num Lock was enabled
          *     }
-         *     if ((mod & KeyEvent.MOD_ALT) == KeyEvent.MOD_ALT) {
+         *     if ((mod & KeyEvent.MOD_ALT) == KeyEvent.MOD_ALT) {
          *         // do something if ONLY the Alt/Option key was down
          *     }
          *     // ...
diff --git a/src/main/java/net/fokinatorr/sparkle/graphics/ARGB.java b/src/main/java/net/fokinatorr/sparkle/graphics/ARGB.java
index 0780ffe..771bfd4 100644
--- a/src/main/java/net/fokinatorr/sparkle/graphics/ARGB.java
+++ b/src/main/java/net/fokinatorr/sparkle/graphics/ARGB.java
@@ -5,10 +5,10 @@ import lombok.experimental.UtilityClass;
 /**
  * Utility methods that help treating an {@code int} value as a ARGB-format color.
  * 

- * ARGB stands for Alpha (opacity), - * Red, - * Green, - * Blue. + * ARGB stands for Alpha (opacity), + * Red, + * Green, + * Blue. * Each of these properties are called color components * or channels. Each component takes up 8 bits of the number, which means they range between 0 and 255 inclusive, and the * resulting component values in blending methods are clamped between that range. diff --git a/src/main/java/net/fokinatorr/sparkle/graphics/font/FilesystemFontProvider.java b/src/main/java/net/fokinatorr/sparkle/graphics/font/FilesystemFontProvider.java index a8960d7..3989016 100644 --- a/src/main/java/net/fokinatorr/sparkle/graphics/font/FilesystemFontProvider.java +++ b/src/main/java/net/fokinatorr/sparkle/graphics/font/FilesystemFontProvider.java @@ -23,16 +23,16 @@ import static lombok.AccessLevel.PRIVATE; * where: *

    *
  • - * <base_dir> is the base directory path provided in the constructor; + * {@code } is the base directory path provided in the constructor; *
  • *
  • - * <family> is the font family name as-is (without replacing spaces or changing case); + * {@code } is the font family name as-is (without replacing spaces or changing case); *
  • *
  • - * <posture> is the font's desired posture in lowercase; + * {@code } is the font's desired posture in lowercase; *
  • *
  • - * <weight> is the font's desired weight in lowercase. + * {@code } is the font's desired weight in lowercase. *
  • *
*/ diff --git a/src/main/java/net/fokinatorr/sparkle/graphics/impl/surface/GLFWToPublicAPI.java b/src/main/java/net/fokinatorr/sparkle/graphics/impl/surface/GLFWToPublicAPI.java index 01bea8d..3c0f9be 100644 --- a/src/main/java/net/fokinatorr/sparkle/graphics/impl/surface/GLFWToPublicAPI.java +++ b/src/main/java/net/fokinatorr/sparkle/graphics/impl/surface/GLFWToPublicAPI.java @@ -10,7 +10,7 @@ import net.fokinatorr.sparkle.event.input.MouseButton; import static org.lwjgl.glfw.GLFW.*; /** - * Maps GLFW key & mouse button codes to public API enums. + * Maps GLFW key & mouse button codes to public API enums. * * @see Key * @see MouseButton diff --git a/src/main/java/net/fokinatorr/sparkle/graphics/render/RenderCanvas.java b/src/main/java/net/fokinatorr/sparkle/graphics/render/RenderCanvas.java index 928f9ce..2cbd41b 100644 --- a/src/main/java/net/fokinatorr/sparkle/graphics/render/RenderCanvas.java +++ b/src/main/java/net/fokinatorr/sparkle/graphics/render/RenderCanvas.java @@ -30,7 +30,7 @@ import java.util.Objects; * top-left corner of the rendering surface. Positive X extends right and positive Y extends down. *

Note for Scratchers: This is different from Scratch's coordinate system. In Scratch, {@code (0, 0)} * is the center of the stage, positive X values extend right and positive Y values extend up. To get - * the center coordinates, use {@link #getDimensions()} to get the width & height of the canvas + * the center coordinates, use {@link #getDimensions()} to get the width & height of the canvas * and divide these values by 2. Vanilla renderers handle conversion between these systems automatically; * custom renderers must do this manually. * @@ -45,16 +45,16 @@ import java.util.Objects; *

  • {@link #setEffects Graphic effects}
  • *
  • Current {@link #clip clipping region}
  • * - * This state can be pushed onto the stack with {@link #save()} and popped & restored with {@link #restore()}. + * This state can be pushed onto the stack with {@link #save()} and popped & restored with {@link #restore()}. * *

    Color Representation

    * Colors are represented as ARGB integers where: *
      - *
    • Bits 0-7: Alpha (opacity) + *
    • Bits 0-7: Alpha (opacity) * component (0 = fully transparent, 255 = fully opaque)
    • - *
    • Bits 8-15: Red component
    • - *
    • Bits 16-23: Green component
    • - *
    • Bits 24-31: Blue component
    • + *
    • Bits 8-15: Red component
    • + *
    • Bits 16-23: Green component
    • + *
    • Bits 24-31: Blue component
    • *
    * *

    Blend Modes

    diff --git a/src/main/java/net/fokinatorr/sparkle/graphics/render/surface/RenderingSurface.java b/src/main/java/net/fokinatorr/sparkle/graphics/render/surface/RenderingSurface.java index b1b1c02..060501a 100644 --- a/src/main/java/net/fokinatorr/sparkle/graphics/render/surface/RenderingSurface.java +++ b/src/main/java/net/fokinatorr/sparkle/graphics/render/surface/RenderingSurface.java @@ -81,7 +81,7 @@ public sealed interface RenderingSurface extends NonThrowingAutoCloseable * Checks whether this surface is translucent (only the rendered content is visible). * This is, in general, determined at creation time and may not change later. * @return whether this surface is translucent - * @implNote The default implementation returns {@code false}. + * @implSpec The default implementation returns {@code false}. */ default boolean isTranslucent() { return false; diff --git a/src/main/java/net/fokinatorr/sparkle/graphics/render/surface/WindowSurface.java b/src/main/java/net/fokinatorr/sparkle/graphics/render/surface/WindowSurface.java index c252030..79cbfc8 100644 --- a/src/main/java/net/fokinatorr/sparkle/graphics/render/surface/WindowSurface.java +++ b/src/main/java/net/fokinatorr/sparkle/graphics/render/surface/WindowSurface.java @@ -9,7 +9,7 @@ import java.util.Set; /** * A window rendering surface. *

    Custom implementations of ths interface are not supported by {@link GraphicsManager}; use its - * {@link GraphicsManager#createWindowContext createWindowContext(...)} methods to create & obtain an instance of this interface. + * {@link GraphicsManager#createWindowContext createWindowContext(...)} methods to create & obtain an instance of this interface. * If you want to insert a stage into a UI framework's window (JavaFX, Swing, etc.) - implement {@link EmbeddedSurface} instead. */ public non-sealed interface WindowSurface extends RenderingSurface { diff --git a/src/main/java/net/fokinatorr/sparkle/phys2d/Hitbox2D.java b/src/main/java/net/fokinatorr/sparkle/phys2d/Hitbox2D.java index a5ce835..fca72dd 100644 --- a/src/main/java/net/fokinatorr/sparkle/phys2d/Hitbox2D.java +++ b/src/main/java/net/fokinatorr/sparkle/phys2d/Hitbox2D.java @@ -117,6 +117,7 @@ public sealed interface Hitbox2D permits AlwaysHitbox2D, AndHitbox2D, NeverHitbo /** * Creates an {@link Area} representing all points covered by this hitbox and applies the given * {@link AffineTransform} instance to it. + * @param affine the transform * @return a new area of this hitbox, if applicable * @see #createArea() */ diff --git a/src/main/java/net/fokinatorr/sparkle/phys2d/Point2D.java b/src/main/java/net/fokinatorr/sparkle/phys2d/Point2D.java index 9c906e7..5518a4c 100644 --- a/src/main/java/net/fokinatorr/sparkle/phys2d/Point2D.java +++ b/src/main/java/net/fokinatorr/sparkle/phys2d/Point2D.java @@ -2,7 +2,7 @@ package net.fokinatorr.sparkle.phys2d; /** * Represents a point in 2D space. - * Can also represent a 2D vector or 2D dimensions (width & height respectively). + * Can also represent a 2D vector or 2D dimensions (width & height respectively). *

    This class has convenience methods for movement. They all can throw an exception as specified * in the {@link #Point2D(double, double) constructor}. * diff --git a/src/main/java/net/fokinatorr/sparkle/util/Global.java b/src/main/java/net/fokinatorr/sparkle/util/Global.java index 6866a9a..aa3691f 100644 --- a/src/main/java/net/fokinatorr/sparkle/util/Global.java +++ b/src/main/java/net/fokinatorr/sparkle/util/Global.java @@ -40,7 +40,7 @@ import java.util.function.Consumer; * {@link Cleaner} (lazy): can be used to clean up resources once an object is no longer used; * *

  • - * {@link AudioManager} (lazy, not in {@linkplain DefaultAppContext#createHeadless() headless}): loads & plays sounds; + * {@link AudioManager} (lazy, not in {@linkplain DefaultAppContext#createHeadless() headless}): loads & plays sounds; *
  • *
  • * {@link SoundDecoder} (not in headless): decodes sound files (mostly used by the audio manager); @@ -124,6 +124,7 @@ public class Global { * @return an object that can be used to remove the listener * @throws IllegalStateException if there is no context for the current thread * @see EventDispatcher#addListener(Class, Consumer) + * @param the type of event */ public ListenerRemover when(Class eventClass, Consumer listener) { return AppContextHolder.getContextOrThrow().get(EventDispatcher.class).addListener(eventClass, listener); diff --git a/src/main/java/net/fokinatorr/sparkle/util/TypeReference.java b/src/main/java/net/fokinatorr/sparkle/util/TypeReference.java index a97c6fe..f36e281 100644 --- a/src/main/java/net/fokinatorr/sparkle/util/TypeReference.java +++ b/src/main/java/net/fokinatorr/sparkle/util/TypeReference.java @@ -12,7 +12,7 @@ import java.lang.reflect.Type; * Type type = typeRef.getType(); // In this example, returns String.class * // do something with the type... * } - * @implNote The class only works when creating a direct subclass. Otherwise, the constructor may throw + * @implSpec The class only works when creating a direct subclass. Otherwise, the constructor may throw * a {@link ClassCastException}. * @param the type to reify */ diff --git a/src/main/java/net/fokinatorr/sparkle/util/WaitUtils.java b/src/main/java/net/fokinatorr/sparkle/util/WaitUtils.java index 7767b88..35f59c0 100644 --- a/src/main/java/net/fokinatorr/sparkle/util/WaitUtils.java +++ b/src/main/java/net/fokinatorr/sparkle/util/WaitUtils.java @@ -10,8 +10,8 @@ import static net.fokinatorr.sparkle.util.Constants.NANOS_PER_MILLISECOND; /** * This class has methods for accurate waiting. *

    Note for Scratchers: This class matches the functionality of Scratch's - * [wait () seconds] and [wait until <>] blocks, and also the functionality of - * PenguinMod's [wait () seconds or until <>] block. + * [wait () seconds] and [wait until <>] blocks, and also the functionality of + * PenguinMod's [wait () seconds or until <>] block. */ @UtilityClass public class WaitUtils { diff --git a/src/main/java/net/fokinatorr/sparkle/variable/ObjectVariable.java b/src/main/java/net/fokinatorr/sparkle/variable/ObjectVariable.java index f9bc504..3b23ee4 100644 --- a/src/main/java/net/fokinatorr/sparkle/variable/ObjectVariable.java +++ b/src/main/java/net/fokinatorr/sparkle/variable/ObjectVariable.java @@ -15,7 +15,7 @@ import java.util.concurrent.atomic.AtomicReference; * import java.util.ArrayList; * import java.util.List; * - * Variable> listVar = new ObjectVariable<>(new ArrayList<>()); + * Variable<List<String>> listVar = new ObjectVariable<>(new ArrayList<>()); * // do something with the list * listVar.getValue().add("Example value"); * // ...