docs: write Javadocs

Author: toxicity188

AGENTS.md

@@ -29,7 +29,8 @@ Javadoc Standards
 
 - Explain the purpose of the class/method in the context of Minecraft server-side rendering.
 - Document `@param` and `@return` types, especially for complex types like MolangCompiler or DisplayEntity.
-- Include `@since` tags corresponding to the current versioning in build.gradle.kts.
+- For Java Record classes, every component (field) must be documented using the `@param` tag.
+- Include `@since` tags corresponding to the current versioning in gradle.properties.
 
 ### Git & Code Interaction
 Commit Messages: Use conventional commits (e.g., docs: add Javadoc for AnimationController).  

api/src/main/java/kr/toxicity/model/api/animation/VectorPoint.java

@@ -16,6 +16,7 @@
  * Vector point
  * @param function function
  * @param time time
+ * @param bezier bezier config
  * @param interpolator interpolator
  */
 public record VectorPoint(@NotNull FloatFunction<Vector3f> function, float time, @NotNull BezierConfig bezier, @NotNull VectorInterpolator interpolator) implements Timed {

api/src/main/java/kr/toxicity/model/api/data/blueprint/BlueprintElement.java

@@ -344,6 +344,7 @@ record Cube(
 
         /**
          * Gets max length of this cube
+         * @param origin origin
          * @return cube length
          */
         public float max(@NotNull Float3 origin) {

api/src/main/java/kr/toxicity/model/api/data/raw/ModelElement.java

@@ -67,8 +67,9 @@ default boolean isSupported() {
 
     /**
      * A raw model's locator
-     * @param name
-     * @param uuid
+     * @param name name
+     * @param uuid uuid
+     * @param position position
      */
     record Locator(
         @NotNull String name,
@@ -100,7 +101,7 @@ record Locator(
 
     /**
      * A raw model's camera
-     * @param uuid
+     * @param uuid uuid
      */
     record Camera(
         @NotNull String uuid
@@ -120,8 +121,8 @@ record Camera(
 
     /**
      * A raw model's null object
-     * @param name
-     * @param uuid
+     * @param name name
+     * @param uuid uuid
      * @param ikTarget ik target
      * @param ikSource ik source
      * @param position position

api/src/main/java/kr/toxicity/model/api/data/raw/ModelTexture.java

@@ -35,6 +35,7 @@ public record ModelTexture(
 
     /**
      * Converts this texture to blueprint textures
+     * @param context context
      * @return converted textures
      */
     public @NotNull BlueprintTexture toBlueprint(@NotNull ModelLoadContext context) {

api/src/main/java/kr/toxicity/model/api/manager/ModelManager.java

@@ -20,22 +20,31 @@
 import java.util.function.Consumer;
 
 /**
- * Model Manager
+ * Manages all loaded models and provides access to them.
+ * <p>
+ * This manager is the primary entry point for retrieving {@link ModelRenderer} instances,
+ * which are used to create and control model trackers.
+ * </p>
+ *
+ * @since 1.15.2
  */
 public interface ModelManager {
 
     /**
-     * Gets renderer by name
-     * @param name name
-     * @return renderer or null
+     * Retrieves a model renderer by its name.
+     *
+     * @param name the name of the model
+     * @return the model renderer, or null if not found
+     * @since 1.15.2
      */
     @Nullable ModelRenderer model(@NotNull String name);
 
 
     /**
-     * @deprecated Use ModelManager#model instead.
-     * @param name name
-     * @return renderer or null
+     * @deprecated Use {@link #model(String)} instead.
+     * @param name the name of the model
+     * @return the model renderer, or null if not found
+     * @since 1.15.2
      */
     @Deprecated
     @Nullable
@@ -44,72 +53,88 @@ default ModelRenderer renderer(@NotNull String name) {
     }
 
     /**
-     * Gets all renderers
-     * @return all renderers
+     * Returns a collection of all loaded model renderers.
+     *
+     * @return an unmodifiable collection of models
+     * @since 1.15.2
      */
     @NotNull @Unmodifiable
     Collection<ModelRenderer> models();
 
     /**
-     * Gets all key of renderer
-     * @return keys
+     * Returns a set of all loaded model names.
+     *
+     * @return an unmodifiable set of model keys
+     * @since 1.15.2
      */
     @NotNull @Unmodifiable
     Set<String> modelKeys();
 
     /**
-     * Gets all renderers for player animation.
-     * @return renderers
+     * Returns a collection of all renderers designated for player limb animations.
+     *
+     * @return an unmodifiable collection of limb models
+     * @since 1.15.2
      */
     @NotNull @Unmodifiable
     Collection<ModelRenderer> limbs();
 
     /**
-     * Gets renderer for player animation by name.
-     * @param name renderer's name
-     * @return renderer or null
+     * Retrieves a player limb renderer by its name.
+     *
+     * @param name the name of the limb model
+     * @return the limb renderer, or null if not found
+     * @since 1.15.2
      */
     @Nullable ModelRenderer limb(@NotNull String name);
 
     /**
-     * Gets all key of renderer
-     * @return keys
+     * Returns a set of all loaded player limb model names.
+     *
+     * @return an unmodifiable set of limb keys
+     * @since 1.15.2
      */
     @NotNull @Unmodifiable
     Set<String> limbKeys();
 
 
     /**
-     * Play's animation to this player
-     * @param player player
-     * @param model model name
-     * @param animation animation name
-     * @return whether to success
+     * Plays an animation on a player.
+     *
+     * @param player the target player
+     * @param model the name of the limb model
+     * @param animation the name of the animation
+     * @return true if the animation started successfully
+     * @since 1.15.2
      */
     default boolean animate(@NotNull Player player, @NotNull String model, @NotNull String animation) {
         return animate(player, model, animation, AnimationModifier.DEFAULT_WITH_PLAY_ONCE);
     }
 
     /**
-     * Play's animation to this player with a specific loop type.
-     * @param player player
-     * @param model model name
-     * @param animation animation name
-     * @param modifier modifier
-     * @return whether to success
+     * Plays an animation on a player with a specific modifier.
+     *
+     * @param player the target player
+     * @param model the name of the limb model
+     * @param animation the name of the animation
+     * @param modifier the animation modifier
+     * @return true if the animation started successfully
+     * @since 1.15.2
      */
     default boolean animate(@NotNull Player player, @NotNull String model, @NotNull String animation, @NotNull AnimationModifier modifier) {
         return animate(player, model, animation, modifier, t -> {});
     }
 
     /**
-     * Play's animation to this player with a specific loop type.
-     * @param player player
-     * @param model model name
-     * @param animation animation name
-     * @param modifier modifier
-     * @param consumer consumer
-     * @return whether to success
+     * Plays an animation on a player with a modifier and a configuration consumer.
+     *
+     * @param player the target player
+     * @param model the name of the limb model
+     * @param animation the name of the animation
+     * @param modifier the animation modifier
+     * @param consumer a consumer to configure the created tracker
+     * @return true if the animation started successfully
+     * @since 1.15.2
      */
     default boolean animate(@NotNull Player player, @NotNull String model, @NotNull String animation, @NotNull AnimationModifier modifier, @NotNull Consumer<EntityTracker> consumer) {
         var get = limb(model);

api/src/main/java/kr/toxicity/model/api/manager/PlayerManager.java

@@ -6,9 +6,6 @@
  */
 package kr.toxicity.model.api.manager;
 
-import kr.toxicity.model.api.BetterModel;
-import kr.toxicity.model.api.animation.AnimationModifier;
-import kr.toxicity.model.api.data.renderer.ModelRenderer;
 import kr.toxicity.model.api.nms.PlayerChannelHandler;
 import org.bukkit.entity.Player;
 import org.jetbrains.annotations.NotNull;
@@ -17,37 +14,33 @@
 import java.util.UUID;
 
 /**
- * Player manager
+ * Manages player-specific data and network channels.
+ * <p>
+ * This manager is responsible for injecting and retrieving {@link PlayerChannelHandler} instances,
+ * which are essential for sending custom packets to players.
+ * </p>
+ *
+ * @since 1.15.2
  */
 public interface PlayerManager {
     /**
-     * Gets player channel handler
-     * @param uuid player's uuid
-     * @return channel handler or null
+     * Retrieves the channel handler for a player by their UUID.
+     *
+     * @param uuid the player's UUID
+     * @return the channel handler, or null if not found
+     * @since 1.15.2
      */
     @Nullable PlayerChannelHandler player(@NotNull UUID uuid);
 
     /**
-     * Get or creates channel handler
-     * Do not use this with fake player, instead use PlayerManager#player(UUID)
-     * @param player player
-     * @return channel handler
+     * Gets or creates the channel handler for a player.
+     * <p>
+     * Note: This should not be used with fake players. Use {@link #player(UUID)} instead for those cases.
+     * </p>
+     *
+     * @param player the player
+     * @return the channel handler
+     * @since 1.15.2
      */
     @NotNull PlayerChannelHandler player(@NotNull Player player);
-
-    @Deprecated(forRemoval = true)
-    @Nullable
-    default ModelRenderer limb(@NotNull String name) {
-        return BetterModel.limbOrNull(name);
-    }
-
-    @Deprecated(forRemoval = true)
-    default boolean animate(@NotNull Player player, @NotNull String model, @NotNull String animation) {
-        return BetterModel.plugin().modelManager().animate(player, model, animation);
-    }
-
-    @Deprecated(forRemoval = true)
-    default boolean animate(@NotNull Player player, @NotNull String model, @NotNull String animation, @NotNull AnimationModifier modifier) {
-        return BetterModel.plugin().modelManager().animate(player, model, animation, modifier);
-    }
-}
+}

api/src/main/java/kr/toxicity/model/api/manager/ProfileManager.java

@@ -11,26 +11,38 @@
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Profile manager
+ * Manages the resolution and creation of model profiles (skins).
+ * <p>
+ * This manager allows configuring the strategy for fetching profiles (e.g., from Mojang API, cache, or custom sources)
+ * and creating skin instances from raw texture data.
+ * </p>
+ *
+ * @since 1.15.2
  */
 public interface ProfileManager {
 
     /**
-     * Gets current supplier
-     * @return current supplier
+     * Returns the current profile supplier strategy.
+     *
+     * @return the profile supplier
+     * @since 1.15.2
      */
     @NotNull ModelProfileSupplier supplier();
 
     /**
-     * Loads skin from raw textures
-     * @param rawTextures textures
-     * @return skin
+     * Creates a {@link ModelProfileSkin} from a raw texture string (Base64 encoded).
+     *
+     * @param rawTextures the raw texture data
+     * @return the created skin profile
+     * @since 1.15.2
      */
     @NotNull ModelProfileSkin skin(@NotNull String rawTextures);
 
     /**
-     * Sets supplier
-     * @param supplier new supplier
+     * Sets the profile supplier strategy.
+     *
+     * @param supplier the new profile supplier
+     * @since 1.15.2
      */
     void supplier(@NotNull ModelProfileSupplier supplier);
 }

api/src/main/java/kr/toxicity/model/api/manager/ReloadInfo.java

@@ -11,8 +11,22 @@
 import org.bukkit.command.CommandSender;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Represents the context for a plugin reload operation.
+ * <p>
+ * This record holds information about who initiated the reload and whether certain parts of the reload should be skipped.
+ * </p>
+ *
+ * @param skipConfig whether to skip reloading the main configuration file
+ * @param sender the command sender who initiated the reload
+ * @since 1.15.2
+ */
 @Builder
 public record ReloadInfo(boolean skipConfig, @NotNull CommandSender sender) {
+    /**
+     * The default reload info, representing a standard reload initiated from the console.
+     * @since 1.15.2
+     */
     public static final ReloadInfo DEFAULT = ReloadInfo.builder()
         .skipConfig(false)
         .sender(Bukkit.getConsoleSender())

api/src/main/java/kr/toxicity/model/api/manager/ScriptManager.java

@@ -12,20 +12,29 @@
 import org.jetbrains.annotations.Nullable;
 
 /**
- * Script manager
+ * Manages the parsing and registration of animation scripts.
+ * <p>
+ * This manager allows for the creation of custom script logic that can be embedded within animations.
+ * </p>
+ *
+ * @since 1.15.2
  */
 public interface ScriptManager {
     /**
-     * Creates a script for line
-     * @param script raw script
-     * @return entity script
+     * Parses a raw script string into an {@link AnimationScript}.
+     *
+     * @param script the raw script string
+     * @return the parsed script, or null if parsing failed
+     * @since 1.15.2
      */
     @Nullable AnimationScript build(@NotNull String script);
 
     /**
-     * Adds script parser to registry
-     * @param name parser name
-     * @param script script builder
+     * Registers a new script builder.
+     *
+     * @param name the name of the parser/builder
+     * @param script the script builder instance
+     * @since 1.15.2
      */
     void addBuilder(@NotNull String name, @NotNull ScriptBuilder script);
 }