fix JavaDoc

This commit is contained in:
Fokinator
2026-05-31 22:05:35 +03:00
parent e788a99545
commit c9a082320d
16 changed files with 36 additions and 33 deletions
@@ -22,7 +22,7 @@ import java.util.Objects;
import java.util.ServiceLoader; import java.util.ServiceLoader;
import java.util.function.Supplier; 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.DEBUG;
import static org.lwjgl.system.Configuration.LIBRARY_PATH; import static org.lwjgl.system.Configuration.LIBRARY_PATH;
@@ -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} * 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). * into a {@link ParsedSound} (PCM data).
* <p><b>Currently supported formats: * <p><b>Currently supported formats:</b>
* <ul> * <ul>
* <li>OGG Vorbis (.ogg)</li> * <li>OGG Vorbis (.ogg)</li>
* </ul></b> * </ul>
* <p><i>Note for Scratchers: Unlike Scratch, which supports many formats (including MP3 and WAV), * <p><i>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. * 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:</i>
* <ol> * <ol>
* <li> * <li>
* <b>Easy way (recommended)</b>: convert them to one of the supported formats * <b>Easy way (recommended)</b>: convert them to one of the supported formats
@@ -33,7 +33,7 @@ import java.util.Set;
* </code></pre> * </code></pre>
* You can get the context using {@link AppContextHolder} utilities. * You can get the context using {@link AppContextHolder} utilities.
* </li> * </li>
* </ol></i> * </ol>
* @see ParsedSound * @see ParsedSound
*/ */
public interface SoundDecoder { public interface SoundDecoder {
@@ -62,7 +62,7 @@ public interface SoundDecoder {
* @return a new parsed sound * @return a new parsed sound
* @throws IOException if an I/O or parse error occurs * @throws IOException if an I/O or parse error occurs
* @throws NullPointerException if input stream is {@code null} * @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. * input stream into an off-heap buffer, parses them and then frees the buffer.
*/ */
default ParsedSound parseStream(InputStream in) throws IOException { default ParsedSound parseStream(InputStream in) throws IOException {
@@ -18,6 +18,7 @@ import java.lang.reflect.InaccessibleObjectException;
* The return value is ignored and can be of any type. * The return value is ignored and can be of any type.
* </li> * </li>
* </ul> * </ul>
* </p>
* <p><i>Note: If you use named modules and a class containing a method annotated with this annotation is not * <p><i>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 * 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} * containing package (respectively) to module {@code ru.fokinatorr.sparkle.core}, otherwise an {@link InaccessibleObjectException}
@@ -9,7 +9,7 @@ import java.util.Objects;
/** /**
* Base interface for events representing a keyboard event. * Base interface for events representing a keyboard event.
* <p><i>Note for Scratchers: This event is similar to the "when [ v] key pressed" in Scratch. Unfortunately, * <p><i>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 &amp; implementations
* to see which event type you need.</i> * to see which event type you need.</i>
*/ */
public sealed interface KeyboardEvent extends InputEvent public sealed interface KeyboardEvent extends InputEvent
@@ -71,13 +71,13 @@ public sealed interface KeyboardEvent extends InputEvent
* <blockquote><pre> * <blockquote><pre>
* // ... * // ...
* int mod = event.modifiers(); * int mod = event.modifiers();
* if ((mod & KeyEvent.MOD_SHIFT) != 0) { * if ((mod &amp; KeyEvent.MOD_SHIFT) != 0) {
* // do something if the Shift key was down * // do something if the Shift key was down
* } * }
* if ((mod & KeyEvent.MOD_NUM_LOCK) != 0) { * if ((mod &amp; KeyEvent.MOD_NUM_LOCK) != 0) {
* // do something if Num Lock was enabled * // do something if Num Lock was enabled
* } * }
* if ((mod & KeyEvent.MOD_ALT) == KeyEvent.MOD_ALT) { * if ((mod &amp; KeyEvent.MOD_ALT) == KeyEvent.MOD_ALT) {
* // do something if ONLY the Alt/Option key was down * // do something if ONLY the Alt/Option key was down
* } * }
* // ... * // ...
@@ -5,10 +5,10 @@ import lombok.experimental.UtilityClass;
/** /**
* Utility methods that help treating an {@code int} value as a ARGB-format color. * Utility methods that help treating an {@code int} value as a ARGB-format color.
* <p> * <p>
* ARGB stands for <span style="background-color: #000000;" color="rgba(255, 255, 255, 0.5)">Alpha</span> (opacity), * ARGB stands for <span style="background-color: #000000; color: rgba(255, 255, 255, 0.5);">Alpha</span> (opacity),
* <span color="#FF0000">Red</span>, * <span style="color: #FF0000">Red</span>,
* <span color="#00FF00">Green</span>, * <span style="color: #00FF00">Green</span>,
* <span color="#0000FF">Blue</span>. * <span style="color: #0000FF">Blue</span>.
* Each of these properties are called color components * 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 * 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. * resulting component values in blending methods are clamped between that range.
@@ -23,16 +23,16 @@ import static lombok.AccessLevel.PRIVATE;
* where: * where:
* <ul> * <ul>
* <li> * <li>
* <tt>&lt;base_dir&gt;</tt> is the base directory path provided in the constructor; * {@code <base_dir>} is the base directory path provided in the constructor;
* </li> * </li>
* <li> * <li>
* <tt>&lt;family&gt;</tt> is the font family name as-is (without replacing spaces or changing case); * {@code <family>} is the font family name as-is (without replacing spaces or changing case);
* </li> * </li>
* <li> * <li>
* <tt>&lt;posture&gt;</tt> is the font's desired posture in lowercase; * {@code <posture>} is the font's desired posture in lowercase;
* </li> * </li>
* <li> * <li>
* <tt>&lt;weight&gt;</tt> is the font's desired weight in lowercase. * {@code <weight>} is the font's desired weight in lowercase.
* </li> * </li>
* </ul> * </ul>
*/ */
@@ -10,7 +10,7 @@ import net.fokinatorr.sparkle.event.input.MouseButton;
import static org.lwjgl.glfw.GLFW.*; import static org.lwjgl.glfw.GLFW.*;
/** /**
* Maps GLFW key & mouse button codes to public API enums. * Maps GLFW key &amp; mouse button codes to public API enums.
* *
* @see Key * @see Key
* @see MouseButton * @see MouseButton
@@ -30,7 +30,7 @@ import java.util.Objects;
* top-left corner of the rendering surface. Positive X extends right and positive Y extends down. * top-left corner of the rendering surface. Positive X extends right and positive Y extends down.
* <p><i><b>Note for Scratchers</b>: This is different from Scratch's coordinate system. In Scratch, {@code (0, 0)} * <p><i><b>Note for Scratchers</b>: 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 * 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 &amp; height of the canvas
* and divide these values by 2. Vanilla renderers handle conversion between these systems automatically; * and divide these values by 2. Vanilla renderers handle conversion between these systems automatically;
* custom renderers must do this manually.</i> * custom renderers must do this manually.</i>
* *
@@ -45,16 +45,16 @@ import java.util.Objects;
* <li>{@link #setEffects Graphic effects}</li> * <li>{@link #setEffects Graphic effects}</li>
* <li>Current {@link #clip clipping region}</li> * <li>Current {@link #clip clipping region}</li>
* </ul> * </ul>
* 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 &amp; restored with {@link #restore()}.
* *
* <h2>Color Representation</h2> * <h2>Color Representation</h2>
* Colors are represented as ARGB integers where: * Colors are represented as ARGB integers where:
* <ul> * <ul>
* <li>Bits 0-7: <span style="background-color: #000000;" color="rgba(255, 255, 255, 0.5)">Alpha</span> (opacity) * <li>Bits 0-7: <span style="background-color: #000000; color: rgba(255, 255, 255, 0.5);">Alpha</span> (opacity)
* component (0 = fully transparent, 255 = fully opaque)</li> * component (0 = fully transparent, 255 = fully opaque)</li>
* <li>Bits 8-15: <span color="#FF0000">Red</span> component</li> * <li>Bits 8-15: <span style="color: #FF0000">Red</span> component</li>
* <li>Bits 16-23: <span color="#00FF00">Green</span> component</li> * <li>Bits 16-23: <span style="color: #00FF00">Green</span> component</li>
* <li>Bits 24-31: <span color="#0000FF">Blue</span> component</li> * <li>Bits 24-31: <span style="color: #0000FF">Blue</span> component</li>
* </ul> * </ul>
* *
* <h2>Blend Modes</h2> * <h2>Blend Modes</h2>
@@ -81,7 +81,7 @@ public sealed interface RenderingSurface extends NonThrowingAutoCloseable
* Checks whether this surface is translucent (only the rendered content is visible). * 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. * This is, in general, determined at creation time and may not change later.
* @return whether this surface is translucent * @return whether this surface is translucent
* @implNote The default implementation returns {@code false}. * @implSpec The default implementation returns {@code false}.
*/ */
default boolean isTranslucent() { default boolean isTranslucent() {
return false; return false;
@@ -9,7 +9,7 @@ import java.util.Set;
/** /**
* A window rendering surface. * A window rendering surface.
* <p>Custom implementations of ths interface are not supported by {@link GraphicsManager}; use its * <p>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 &amp; 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. * 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 { public non-sealed interface WindowSurface extends RenderingSurface {
@@ -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 * Creates an {@link Area} representing all points covered by this hitbox and applies the given
* {@link AffineTransform} instance to it. * {@link AffineTransform} instance to it.
* @param affine the transform
* @return a new area of this hitbox, if applicable * @return a new area of this hitbox, if applicable
* @see #createArea() * @see #createArea()
*/ */
@@ -2,7 +2,7 @@ package net.fokinatorr.sparkle.phys2d;
/** /**
* Represents a point in 2D space. * 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 &amp; height respectively).
* <p>This class has convenience methods for movement. They all can throw an exception as specified * <p>This class has convenience methods for movement. They all can throw an exception as specified
* in the {@link #Point2D(double, double) constructor}. * in the {@link #Point2D(double, double) constructor}.
* *
@@ -40,7 +40,7 @@ import java.util.function.Consumer;
* {@link Cleaner} <b>(lazy)</b>: can be used to clean up resources once an object is no longer used; * {@link Cleaner} <b>(lazy)</b>: can be used to clean up resources once an object is no longer used;
* </li> * </li>
* <li> * <li>
* {@link AudioManager} <b>(lazy, not in {@linkplain DefaultAppContext#createHeadless() headless})</b>: loads & plays sounds; * {@link AudioManager} <b>(lazy, not in {@linkplain DefaultAppContext#createHeadless() headless})</b>: loads &amp; plays sounds;
* </li> * </li>
* <li> * <li>
* {@link SoundDecoder} <b>(not in headless)</b>: decodes sound files (mostly used by the audio manager); * {@link SoundDecoder} <b>(not in headless)</b>: 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 * @return an object that can be used to remove the listener
* @throws IllegalStateException if there is no context for the current thread * @throws IllegalStateException if there is no context for the current thread
* @see EventDispatcher#addListener(Class, Consumer) * @see EventDispatcher#addListener(Class, Consumer)
* @param <E> the type of event
*/ */
public <E extends Event> ListenerRemover when(Class<E> eventClass, Consumer<? super E> listener) { public <E extends Event> ListenerRemover when(Class<E> eventClass, Consumer<? super E> listener) {
return AppContextHolder.getContextOrThrow().get(EventDispatcher.class).addListener(eventClass, listener); return AppContextHolder.getContextOrThrow().get(EventDispatcher.class).addListener(eventClass, listener);
@@ -12,7 +12,7 @@ import java.lang.reflect.Type;
* Type type = typeRef.getType(); // In this example, returns String.class * Type type = typeRef.getType(); // In this example, returns String.class
* // do something with the type... * // do something with the type...
* } * }
* @implNote <i>The class only works when creating a direct subclass.</i> Otherwise, the constructor may throw * @implSpec <i>The class only works when creating a direct subclass.</i> Otherwise, the constructor may throw
* a {@link ClassCastException}. * a {@link ClassCastException}.
* @param <T> the type to reify * @param <T> the type to reify
*/ */
@@ -10,8 +10,8 @@ import static net.fokinatorr.sparkle.util.Constants.NANOS_PER_MILLISECOND;
/** /**
* This class has methods for accurate waiting. * This class has methods for accurate waiting.
* <p><i>Note for Scratchers: This class matches the functionality of Scratch's * <p><i>Note for Scratchers: This class matches the functionality of Scratch's
* [wait () seconds] and [wait until <>] blocks, and also the functionality of * [wait () seconds] and [wait until &lt;&gt;] blocks, and also the functionality of
* PenguinMod's [wait () seconds or until <>] block.</i> * PenguinMod's [wait () seconds or until &lt;&gt;] block.</i>
*/ */
@UtilityClass @UtilityClass
public class WaitUtils { public class WaitUtils {
@@ -15,7 +15,7 @@ import java.util.concurrent.atomic.AtomicReference;
* import java.util.ArrayList; * import java.util.ArrayList;
* import java.util.List; * import java.util.List;
* *
* Variable<List<String>> listVar = new ObjectVariable<>(new ArrayList<>()); * Variable&lt;List&lt;String&gt;&gt; listVar = new ObjectVariable&lt;&gt;(new ArrayList&lt;&gt;());
* // do something with the list * // do something with the list
* listVar.getValue().add("Example value"); * listVar.getValue().add("Example value");
* // ... * // ...