chore(core): add apiguardian @API annotations

Incendo · Jun 6, 2022 · d4c6103 · d4c6103
1 parent 990fbe7
commit d4c6103
Show file tree

Hide file tree

Showing 107 changed files with 492 additions and 18 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Core: Add delegating command execution handlers ([#363](https://github.com/Incendo/cloud/pull/363))
 - Core: Add `builder()` getter to `Command.Builder` ([#363](https://github.com/Incendo/cloud/pull/363))
 - Core: Add flag yielding modes to `StringArgument` and `StringArrayArgument` ([#367](https://github.com/Incendo/cloud/pull/367))
+- Core: Add [apiguardian](https://github.com/apiguardian-team/apiguardian) `@API` annotations ([#368](https://github.com/Incendo/cloud/pull/368))
 - Annotations: Annotation string processors ([#353](https://github.com/Incendo/cloud/pull/353))
 - Annotations: `@CommandContainer` annotation processing ([#364](https://github.com/Incendo/cloud/pull/364))
 - Annotations: `@CommandMethod` annotation processing for compile-time validation ([#365](https://github.com/Incendo/cloud/pull/365))

diff --git a/build-logic/src/main/kotlin/cloud.base-conventions.gradle.kts b/build-logic/src/main/kotlin/cloud.base-conventions.gradle.kts
@@ -110,6 +110,8 @@ repositories {
 
 dependencies {
     compileOnlyApi(libs.checkerQual)
+    compileOnlyApi(libs.apiguardian)
+
     testImplementation(libs.jupiterEngine)
     testImplementation(libs.jupiterParams)
     testImplementation(libs.mockitoCore)

diff --git a/cloud-core/src/main/java/cloud/commandframework/ArgumentDescription.java b/cloud-core/src/main/java/cloud/commandframework/ArgumentDescription.java
@@ -24,6 +24,7 @@
 package cloud.commandframework;
 
 import cloud.commandframework.arguments.CommandArgument;
+import org.apiguardian.api.API;
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 import static java.util.Objects.requireNonNull;
@@ -33,6 +34,7 @@
  *
  * @since 1.4.0
  */
+@API(status = API.Status.STABLE, since = "1.4.0")
 public interface ArgumentDescription {
 
     /**

diff --git a/cloud-core/src/main/java/cloud/commandframework/Command.java b/cloud-core/src/main/java/cloud/commandframework/Command.java
@@ -48,6 +48,7 @@
 import java.util.function.BiFunction;
 import java.util.function.Consumer;
 import java.util.stream.Collectors;
+import org.apiguardian.api.API;
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
@@ -56,6 +57,7 @@
  *
  * @param <C> Command sender type
  */
+@API(status = API.Status.STABLE)
 public class Command<C> {
 
     private final List<@NonNull CommandComponent<C>> components;
@@ -75,6 +77,7 @@ public class Command<C> {
      * @param commandMeta             Command meta instance
      * @since 1.3.0
      */
+    @API(status = API.Status.STABLE, since = "1.3.0")
     public Command(
             final @NonNull List<@NonNull CommandComponent<C>> commandComponents,
             final @NonNull CommandExecutionHandler<@NonNull C> commandExecutionHandler,
@@ -118,6 +121,7 @@ public Command(
      * @param commandMeta             Command meta instance
      * @since 1.3.0
      */
+    @API(status = API.Status.STABLE, since = "1.3.0")
     public Command(
             final @NonNull List<@NonNull CommandComponent<C>> commandComponents,
             final @NonNull CommandExecutionHandler<@NonNull C> commandExecutionHandler,
@@ -136,6 +140,7 @@ public Command(
      * @param commandMeta             Command meta instance
      * @since 1.3.0
      */
+    @API(status = API.Status.STABLE, since = "1.3.0")
     public Command(
             final @NonNull List<@NonNull CommandComponent<C>> commandComponents,
             final @NonNull CommandExecutionHandler<@NonNull C> commandExecutionHandler,
@@ -157,6 +162,7 @@ public Command(
      * @see #Command(List, CommandExecutionHandler, Class, CommandPermission, CommandMeta)
      */
     @Deprecated
+    @API(status = API.Status.DEPRECATED)
     public Command(
             final @NonNull Map<@NonNull CommandArgument<C, ?>, @NonNull Description> commandArguments,
             final @NonNull CommandExecutionHandler<@NonNull C> commandExecutionHandler,
@@ -178,6 +184,7 @@ public Command(
      * @see #Command(List, CommandExecutionHandler, Class, CommandMeta)
      */
     @Deprecated
+    @API(status = API.Status.DEPRECATED)
     public Command(
             final @NonNull Map<@NonNull CommandArgument<C, ?>, @NonNull Description> commandArguments,
             final @NonNull CommandExecutionHandler<@NonNull C> commandExecutionHandler,
@@ -198,6 +205,7 @@ public Command(
      * @see #Command(List, CommandExecutionHandler, CommandPermission, CommandMeta)
      */
     @Deprecated
+    @API(status = API.Status.DEPRECATED)
     public Command(
             final @NonNull Map<@NonNull CommandArgument<C, ?>, @NonNull Description> commandArguments,
             final @NonNull CommandExecutionHandler<@NonNull C> commandExecutionHandler,
@@ -231,6 +239,7 @@ public Command(
      * @deprecated for removal since 1.4.0. Use {@link #newBuilder(String, CommandMeta, ArgumentDescription, String...)} instead.
      */
     @Deprecated
+    @API(status = API.Status.DEPRECATED, since = "1.4.0")
     public static <C> @NonNull Builder<C> newBuilder(
             final @NonNull String commandName,
             final @NonNull CommandMeta commandMeta,
@@ -252,6 +261,7 @@ public Command(
      * @return Command builder
      * @since 1.4.0
      */
+    @API(status = API.Status.STABLE, since = "1.4.0")
     public static <C> @NonNull Builder<C> newBuilder(
             final @NonNull String commandName,
             final @NonNull CommandMeta commandMeta,
@@ -314,6 +324,7 @@ public Command(
      * @return Copy of the command component array. This List is mutable
      * @since 1.3.0
      */
+    @API(status = API.Status.STABLE, since = "1.3.0")
     public @NonNull List<CommandComponent<@NonNull C>> getComponents() {
         return new ArrayList<>(this.components);
     }
@@ -364,6 +375,7 @@ public Command(
      *             Use {@link #getArguments()} and search in that, instead.
      */
     @Deprecated
+    @API(status = API.Status.DEPRECATED)
     public @NonNull String getArgumentDescription(final @NonNull CommandArgument<C, ?> argument) {
         for (final CommandComponent<C> component : this.components) {
             if (component.getArgument().equals(argument)) {
@@ -384,7 +396,7 @@ public final String toString() {
     }
 
     /**
-     * Check whether or not the command is hidden
+     * Check whether the command is hidden
      *
      * @return {@code true} if the command is hidden, {@code false} if not
      */
@@ -399,6 +411,7 @@ public boolean isHidden() {
      *
      * @param <C> Command sender type
      */
+    @API(status = API.Status.STABLE)
     public static final class Builder<C> {
 
         private final CommandMeta commandMeta;
@@ -435,6 +448,7 @@ private Builder(
          * @return required sender type
          * @since 1.3.0
          */
+        @API(status = API.Status.STABLE, since = "1.3.0")
         public @Nullable Class<? extends C> senderType() {
             return this.senderType;
         }
@@ -447,6 +461,7 @@ private Builder(
          * @return required permission
          * @since 1.3.0
          */
+        @API(status = API.Status.STABLE, since = "1.3.0")
         public @NonNull CommandPermission commandPermission() {
             return this.commandPermission;
         }
@@ -460,6 +475,7 @@ private Builder(
          * @deprecated for removal since 1.2.0, use the typesafe variant at {@link #meta(CommandMeta.Key, Object)} instead.
          */
         @Deprecated
+        @API(status = API.Status.DEPRECATED, since = "1.2.0")
         public @NonNull Builder<C> meta(final @NonNull String key, final @NonNull String value) {
             final CommandMeta commandMeta = SimpleCommandMeta.builder().with(this.commandMeta).with(key, value).build();
             return new Builder<>(
@@ -482,6 +498,7 @@ private Builder(
          * @return New builder instance using the inserted meta key-value pair
          * @since 1.3.0
          */
+        @API(status = API.Status.STABLE, since = "1.3.0")
         public <V> @NonNull Builder<C> meta(final CommandMeta.@NonNull Key<V> key, final @NonNull V value) {
             final CommandMeta commandMeta = SimpleCommandMeta.builder().with(this.commandMeta).with(key, value).build();
             return new Builder<>(
@@ -539,6 +556,7 @@ private Builder(
          * @deprecated for removal since 1.4.0. Use {@link #literal(String, ArgumentDescription, String...)} instead.
          */
         @Deprecated
+        @API(status = API.Status.DEPRECATED, since = "1.4.0")
         public @NonNull Builder<C> literal(
                 final @NonNull String main,
                 final @NonNull Description description,
@@ -556,6 +574,7 @@ private Builder(
          * @return New builder instance with the modified command chain
          * @since 1.4.0
          */
+        @API(status = API.Status.STABLE, since = "1.4.0")
         public @NonNull Builder<C> literal(
                 final @NonNull String main,
                 final @NonNull ArgumentDescription description,
@@ -597,6 +616,7 @@ private Builder(
          * @deprecated for removal since 1.4.0. Use {@link #argument(CommandArgument, ArgumentDescription)} instead.
          */
         @Deprecated
+        @API(status = API.Status.DEPRECATED, since = "1.4.0")
         public <T> @NonNull Builder<C> argument(
                 final @NonNull CommandArgument<C, T> argument,
                 final @NonNull Description description
@@ -613,6 +633,7 @@ private Builder(
          * @return New builder instance with the command argument inserted into the argument list
          * @since 1.4.0
          */
+        @API(status = API.Status.STABLE, since = "1.4.0")
         public <T> @NonNull Builder<C> argument(
                 final @NonNull CommandArgument<C, T> argument,
                 final @NonNull ArgumentDescription description
@@ -646,6 +667,7 @@ private Builder(
          * @deprecated for removal since 1.4.0. Use {@link #argument(CommandArgument.Builder, ArgumentDescription)} instead.
          */
         @Deprecated
+        @API(status = API.Status.DEPRECATED, since = "1.4.0")
         public <T> @NonNull Builder<C> argument(
                 final CommandArgument.@NonNull Builder<C, T> builder,
                 final @NonNull Description description
@@ -663,6 +685,7 @@ private Builder(
          * @return New builder instance with the command argument inserted into the argument list
          * @since 1.4.0
          */
+        @API(status = API.Status.STABLE, since = "1.4.0")
         public <T> @NonNull Builder<C> argument(
                 final CommandArgument.@NonNull Builder<C, T> builder,
                 final @NonNull ArgumentDescription description
@@ -723,6 +746,7 @@ private Builder(
          * @deprecated for removal since 1.4.0. Use {@link #argumentPair(String, Pair, Pair, ArgumentDescription)} instead.
          */
         @Deprecated
+        @API(status = API.Status.DEPRECATED, since = "1.4.0")
         public <U, V> @NonNull Builder<C> argumentPair(
                 final @NonNull String name,
                 final @NonNull Pair<@NonNull String, @NonNull String> names,
@@ -750,6 +774,7 @@ private Builder(
          * @return Builder instance with the argument inserted
          * @since 1.4.0
          */
+        @API(status = API.Status.STABLE, since = "1.4.0")
         public <U, V> @NonNull Builder<C> argumentPair(
                 final @NonNull String name,
                 final @NonNull Pair<@NonNull String, @NonNull String> names,
@@ -785,6 +810,7 @@ private Builder(
          *     {@link #argumentPair(String, TypeToken, Pair, Pair, BiFunction, ArgumentDescription)} instead.
          */
         @Deprecated
+        @API(status = API.Status.DEPRECATED, since = "1.4.0")
         public <U, V, O> @NonNull Builder<C> argumentPair(
                 final @NonNull String name,
                 final @NonNull TypeToken<O> outputType,
@@ -817,6 +843,7 @@ private Builder(
          * @return Builder instance with the argument inserted
          * @since 1.4.0
          */
+        @API(status = API.Status.STABLE, since = "1.4.0")
         public <U, V, O> @NonNull Builder<C> argumentPair(
                 final @NonNull String name,
                 final @NonNull TypeToken<O> outputType,
@@ -855,6 +882,7 @@ private Builder(
          *     instead.
          */
         @Deprecated
+        @API(status = API.Status.DEPRECATED, since = "1.4.0")
         public <U, V, W> @NonNull Builder<C> argumentTriplet(
                 final @NonNull String name,
                 final @NonNull Triplet<String, String, String> names,
@@ -883,6 +911,7 @@ private Builder(
          * @return Builder instance with the argument inserted
          * @since 1.4.0
          */
+        @API(status = API.Status.STABLE, since = "1.4.0")
         public <U, V, W> @NonNull Builder<C> argumentTriplet(
                 final @NonNull String name,
                 final @NonNull Triplet<String, String, String> names,
@@ -919,6 +948,7 @@ private Builder(
          *      {@link #argumentTriplet(String, TypeToken, Triplet, Triplet, BiFunction, ArgumentDescription)} instead.
          */
         @Deprecated
+        @API(status = API.Status.DEPRECATED, since = "1.4.0")
         public <U, V, W, O> @NonNull Builder<C> argumentTriplet(
                 final @NonNull String name,
                 final @NonNull TypeToken<O> outputType,
@@ -959,6 +989,7 @@ private Builder(
          * @return Builder instance with the argument inserted
          * @since 1.4.0
          */
+        @API(status = API.Status.STABLE, since = "1.4.0")
         public <U, V, W, O> @NonNull Builder<C> argumentTriplet(
                 final @NonNull String name,
                 final @NonNull TypeToken<O> outputType,
@@ -1002,6 +1033,7 @@ private Builder(
          * @return the current handler
          * @since 1.7.0
          */
+        @API(status = API.Status.STABLE, since = "1.7.0")
         public @NonNull CommandExecutionHandler<C> handler() {
             return this.commandExecutionHandler;
         }

diff --git a/cloud-core/src/main/java/cloud/commandframework/CommandComponent.java b/cloud-core/src/main/java/cloud/commandframework/CommandComponent.java
@@ -25,6 +25,7 @@
 
 import cloud.commandframework.arguments.CommandArgument;
 import java.util.Objects;
+import org.apiguardian.api.API;
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
@@ -33,6 +34,7 @@
  * @param <C> Command sender type
  * @since 1.3.0
  */
+@API(status = API.Status.STABLE, since = "1.3.0")
 public final class CommandComponent<C> {
 
     private final CommandArgument<C, ?> argument;
@@ -68,6 +70,7 @@ private CommandComponent(
      * @deprecated for removal since 1.4.0. Use {@link #getArgumentDescription()} instead.
      */
     @Deprecated
+    @API(status = API.Status.DEPRECATED, since = "1.4.0")
     public @NonNull Description getDescription() {
         if (this.description instanceof Description) {
             return (Description) this.description;
@@ -82,6 +85,7 @@ private CommandComponent(
      * @return command component description
      * @since 1.4.0
      */
+    @API(status = API.Status.STABLE, since = "1.4.0")
     public @NonNull ArgumentDescription getArgumentDescription() {
         return this.description;
     }
@@ -120,6 +124,7 @@ public boolean equals(final Object o) {
      * @deprecated for removal since 1.4.0. Use {@link #of(CommandArgument, ArgumentDescription)} instead.
      */
     @Deprecated
+    @API(status = API.Status.DEPRECATED, since = "1.4.0")
     public static <C> @NonNull CommandComponent<C> of(
             final @NonNull CommandArgument<C, ?> commandArgument,
             final @NonNull Description commandDescription