Bump remaining tedious dependencies and misc. changes

api/build.gradle.kts

@@ -24,7 +24,7 @@ dependencies {
     api(libs.guava)
 
     // DEPRECATED: Will be removed in Velocity Polymer
-    api("com.moandjiezana.toml:toml4j:0.7.2")
+    api("io.hotmoka:toml4j:0.7.3")
 
     api(platform(libs.adventure.bom))
     api("net.kyori:adventure-api")
@@ -55,8 +55,6 @@ tasks {
         }
     }
     withType<Javadoc> {
-        exclude("com/velocitypowered/api/plugin/ap/**")
-
         val o = options as StandardJavadocDocletOptions
         o.encoding = "UTF-8"
         o.source = "21"
@@ -66,7 +64,7 @@ tasks {
             "https://www.javadocs.dev/org.slf4j/slf4j-api/${libs.slf4j.get().version}/",
             "https://guava.dev/releases/${libs.guava.get().version}/api/docs/",
             "https://google.github.io/guice/api-docs/${libs.guice.get().version}/javadoc/",
-            "https://docs.oracle.com/en/java/javase/17/docs/api/",
+            "https://docs.oracle.com/en/java/javase/21/docs/api/",
             "https://jd.advntr.dev/api/${libs.adventure.bom.get().version}/",
             "https://jd.advntr.dev/text-minimessage/${libs.adventure.bom.get().version}/",
             "https://jd.advntr.dev/key/${libs.adventure.bom.get().version}/",
@@ -79,8 +77,5 @@ tasks {
             "implNote:a:Implementation Note:",
             "sinceMinecraft:a:Since Minecraft:"
         )
-
-        // Disable the crazy super-strict doclint tool in Java 8
-        o.addStringOption("Xdoclint:none", "-quiet")
     }
 }

api/src/ap/java/com/velocitypowered/api/plugin/ap/PluginAnnotationProcessor.java

@@ -36,6 +36,15 @@
 @SupportedAnnotationTypes({"com.velocitypowered.api.plugin.Plugin"})
 public class PluginAnnotationProcessor extends AbstractProcessor {
 
+  /**
+   * Creates a new {@code PluginAnnotationProcessor}.
+   *
+   * <p>The processor is instantiated by the Java compiler and initialized via
+   * {@link #init(ProcessingEnvironment)}.</p>
+   */
+  public PluginAnnotationProcessor() {
+  }
+
   private ProcessingEnvironment environment;
   private String pluginClassFound;
   private boolean warnedAboutMultiplePlugins;

api/src/ap/java/com/velocitypowered/api/plugin/ap/SerializedPluginDescription.java

@@ -24,7 +24,19 @@
  */
 public final class SerializedPluginDescription {
 
+  /**
+   * The string pattern used to validate plugin IDs.
+   *
+   * <p>Plugin IDs must start with a lowercase letter and may contain lowercase letters,
+   * digits, hyphens, and underscores. The total length must not exceed 64 characters.</p>
+   */
   public static final String ID_PATTERN_STRING = "[a-z][a-z0-9-_]{0,63}";
+  /**
+   * The compiled pattern used to validate plugin IDs.
+   *
+   * <p>Plugin IDs must start with a lowercase letter and may contain lowercase letters,
+   * digits, hyphens, and underscores. The total length must not exceed 64 characters.</p>
+   */
   public static final Pattern ID_PATTERN = Pattern.compile(ID_PATTERN_STRING);
 
   // @Nullable is used here to make GSON skip these in the serialized file
@@ -64,34 +76,78 @@ static SerializedPluginDescription from(Plugin plugin, String qualifiedName) {
             .collect(Collectors.toList()), dependencies, qualifiedName);
   }
 
+  /**
+   * Gets the ID of the plugin this dependency refers to.
+   *
+   * @return the plugin ID
+   */
   public String getId() {
     return id;
   }
 
+  /**
+   * Gets the human-readable name of the plugin.
+   *
+   * @return the plugin's name, or {@code null} if not specified
+   */
   public @Nullable String getName() {
     return name;
   }
 
+  /**
+   * Gets the version string of the plugin.
+   *
+   * @return the plugin version, or {@code null} if not specified
+   */
   public @Nullable String getVersion() {
     return version;
   }
 
+  /**
+   * Gets the plugin's description, typically a short summary of its functionality.
+   *
+   * @return the description, or {@code null} if not specified
+   */
   public @Nullable String getDescription() {
     return description;
   }
 
+  /**
+   * Gets the website URL for the plugin.
+   *
+   * <p>This is often used to link to documentation, support, or the plugin's homepage.</p>
+   *
+   * @return the plugin URL, or {@code null} if not specified
+   */
   public @Nullable String getUrl() {
     return url;
   }
 
+  /**
+   * Gets the list of authors who contributed to the plugin.
+   *
+   * @return an immutable list of authors; empty if none were specified
+   */
   public List<String> getAuthors() {
     return authors == null ? ImmutableList.of() : authors;
   }
 
+  /**
+   * Gets the list of declared dependencies for the plugin.
+   *
+   * <p>Dependencies may be required or optional and describe other plugins, this one depends.</p>
+   *
+   * @return an immutable list of plugin dependencies
+   */
   public List<Dependency> getDependencies() {
     return dependencies == null ? ImmutableList.of() : dependencies;
   }
 
+  /**
+   * Gets the fully qualified name of the plugin's main class.
+   *
+   * @return the main class name
+   */
   public String getMain() {
     return main;
   }
@@ -142,15 +198,33 @@ public static final class Dependency {
     private final String id;
     private final boolean optional;
 
+    /**
+     * Constructs a new dependency class.
+     *
+     * @param id the ID of the dependent plugin
+     * @param optional whether the dependency is optional
+     */
     public Dependency(String id, boolean optional) {
       this.id = id;
       this.optional = optional;
     }
 
+    /**
+     * Gets the ID of the plugin this dependency refers to.
+     *
+     * @return the plugin ID
+     */
     public String getId() {
       return id;
     }
 
+    /**
+     * Indicates whether this dependency is optional.
+     *
+     * <p>Optional dependencies are not required for the plugin to load.</p>
+     *
+     * @return {@code true} if the dependency is optional; {@code false} otherwise
+     */
     public boolean isOptional() {
       return optional;
     }

api/src/main/java/com/velocitypowered/api/command/CommandSource.java

@@ -25,20 +25,20 @@ public interface CommandSource extends Audience, PermissionSubject {
    * @param message MiniMessage content
    * @see <a href="https://docs.advntr.dev/minimessage/format.html">MiniMessage docs</a>
    *      for more information on the format.
-   **/
+   */
   default void sendRichMessage(final @NotNull String message) {
     this.sendMessage(MiniMessage.miniMessage().deserialize(message, this));
   }
 
   /**
-  * Sends a message with the MiniMessage format to this source.
-  *
-  * @param message MiniMessage content
-  * @param resolvers resolvers to use
-  * @see <a href="https://docs.advntr.dev/minimessage/">MiniMessage docs</a>
-  *     and <a href="https://docs.advntr.dev/minimessage/dynamic-replacements">MiniMessage Placeholders docs</a>
-  *     for more information on the format.
-  **/
+   * Sends a message with the MiniMessage format to this source.
+   *
+   * @param message MiniMessage content
+   * @param resolvers resolvers to use
+   * @see <a href="https://docs.advntr.dev/minimessage/">MiniMessage docs</a>
+   *     and <a href="https://docs.advntr.dev/minimessage/dynamic-replacements">MiniMessage Placeholders docs</a>
+   *     for more information on the format.
+   */
   default void sendRichMessage(
           final @NotNull String message,
           final @NotNull TagResolver @NotNull... resolvers
@@ -47,13 +47,13 @@ default void sendRichMessage(
   }
 
   /**
-  * Sends a plain message to this source.
-  *
-  * @param message plain message
-  * @apiNote This method will not apply any form of parse to the text provided,
-  *      however, it is recommended not to use legacy color codes as this is a deprecated format
+   * Sends a plain message to this source.
+   *
+   * @param message plain message
+   * @apiNote This method will not apply any form of parse to the text provided,
+   *      however, it is recommended not to use legacy color codes as this is a deprecated format
    *     and not recommended.
-  */
+   */
   default void sendPlainMessage(final @NotNull String message) {
     this.sendMessage(Component.text(message));
   }

api/src/main/java/com/velocitypowered/api/command/VelocityBrigadierMessage.java

@@ -20,6 +20,12 @@
  */
 public final class VelocityBrigadierMessage implements Message, ComponentLike {
 
+  /**
+   * Creates a new {@link VelocityBrigadierMessage} using the given {@link Component} as the message.
+   *
+   * @param message the component to use as the tooltip message
+   * @return a new instance of {@link VelocityBrigadierMessage}
+   */
   public static VelocityBrigadierMessage tooltip(Component message) {
     return new VelocityBrigadierMessage(message);
   }

api/src/main/java/com/velocitypowered/api/event/Continuation.java

@@ -20,6 +20,8 @@ public interface Continuation {
 
   /**
    * Resumes the continuation after the executed task failed.
+   *
+   * @param exception the {@link Throwable} that caused the failure
    */
   void resumeWithException(Throwable exception);
-}
+}

api/src/main/java/com/velocitypowered/api/event/EventHandler.java

@@ -13,12 +13,28 @@
  * Represents an interface to perform direct dispatch of an event. This makes integration easier to
  * achieve with platforms such as RxJava. While this interface can be used to implement an awaiting
  * event handler, {@link AwaitingEventExecutor} provides a more idiomatic means to doing so.
+ *
+ * @param <E> the event type this handler accepts
  */
 @FunctionalInterface
 public interface EventHandler<E> {
 
+  /**
+   * Executes this handler synchronously with the given event.
+   *
+   * @param event the event to handle
+   */
   void execute(E event);
 
+  /**
+   * Executes this handler asynchronously with the given event.
+   *
+   * <p>If asynchronous handling is not implemented, the event is executed synchronously
+   * and this method returns {@code null}.</p>
+   *
+   * @param event the event to handle
+   * @return an {@link EventTask} representing the async task, or {@code null} if not async
+   */
   default @Nullable EventTask executeAsync(E event) {
     execute(event);
     return null;

api/src/main/java/com/velocitypowered/api/event/EventManager.java

@@ -73,6 +73,7 @@ <E> void register(Object plugin, Class<E> eventClass, short postOrder,
    * servicing connections while a plugin handles a potentially long-running operation such as a
    * database query.
    *
+   * @param <E> the event type
    * @param event the event to fire
    * @return a {@link CompletableFuture} representing the posted event
    */

api/src/main/java/com/velocitypowered/api/event/PostOrder.java

@@ -12,7 +12,34 @@
  */
 public enum PostOrder {
 
-  FIRST, EARLY, NORMAL, LATE, LAST,
+  /**
+   * Indicates the listener should be invoked first, before any other listener.
+   * This order is suitable for listeners that must handle the event before others.
+   */
+  FIRST,
+  /**
+   * Indicates the listener should be invoked early, but after listeners with {@link #FIRST}.
+   * This order is suitable for handling the event before most other listeners.
+   */
+  EARLY,
+  /**
+   * Indicates the listener should be invoked in the normal order of execution.
+   * This is the default and most commonly used order.
+   */
+  NORMAL,
+  /**
+   * Indicates the listener should be invoked later in the execution order,
+   * after listeners with {@link #NORMAL}.
+   * This order is suitable for listeners that should observe the results of
+   * earlier listeners.
+   */
+  LATE,
+  /**
+   * Indicates the listener should be invoked last, after all other listeners.
+   * This order is suitable for listeners that should run only after all others
+   * have completed handling the event.
+   */
+  LAST,
 
   /**
    * Previously used to specify that {@link Subscribe#priority()} should be used.