Tweak @PlatformAPI implementation and use @ApiStatus.Internal to prod…

…uce warnings
KyoriPowered · Nov 9, 2022 · 9630a8a · 9630a8a
1 parent 36efb91
commit 9630a8a
Show file tree

Hide file tree

Showing 6 changed files with 28 additions and 3 deletions.
diff --git a/api/src/main/java/net/kyori/adventure/bossbar/HackyBossBarPlatformBridge.java b/api/src/main/java/net/kyori/adventure/bossbar/HackyBossBarPlatformBridge.java
@@ -24,13 +24,15 @@
 package net.kyori.adventure.bossbar;
 
 import net.kyori.adventure.util.PlatformAPI;
+import org.jetbrains.annotations.ApiStatus;
 
 /**
  * This class is a major hack, intended to allow certain platforms a way
  * to define a platform-native counterpart to an Adventure boss bar.
  *
  * @deprecated not an official API, and may disappear without warning
  */
+@ApiStatus.Internal
 @Deprecated
 @PlatformAPI
 abstract class HackyBossBarPlatformBridge {

diff --git a/api/src/main/java/net/kyori/adventure/util/PlatformAPI.java b/api/src/main/java/net/kyori/adventure/util/PlatformAPI.java
@@ -23,20 +23,25 @@
  */
 package net.kyori.adventure.util;
 
+import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 import org.jetbrains.annotations.ApiStatus;
 
 /**
- * Elements annotated with the {@code @PlatformAPI} annotation are intended for platform implementations of the Adventure api
- * only.
+ * Elements annotated with the {@link PlatformAPI} annotation are intended for platform implementations of the Adventure API
+ * only and should not be used by standard developers. They are not public API and may change or be removed without warning at any time.
+ *
+ * <p>This annotation should always be used in tandem with the {@link ApiStatus.Internal} annotation to more consistently produce
+ * warnings</p>
  *
  * @since 4.12.0
  */
 @ApiStatus.Internal
-@Target({ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.PACKAGE})
+@Documented
 @Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.PACKAGE, ElementType.ANNOTATION_TYPE})
 public @interface PlatformAPI {
 }
diff --git a/text-minimessage/src/main/java/net/kyori/adventure/text/minimessage/MiniMessage.java b/text-minimessage/src/main/java/net/kyori/adventure/text/minimessage/MiniMessage.java
@@ -31,6 +31,7 @@
 import net.kyori.adventure.text.minimessage.tree.Node;
 import net.kyori.adventure.text.serializer.ComponentSerializer;
 import net.kyori.adventure.util.PlatformAPI;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
@@ -298,6 +299,7 @@ interface Builder extends AbstractBuilder<MiniMessage> {
    * @since 4.10.0
    * @hidden
    */
+  @ApiStatus.Internal
   @PlatformAPI
   interface Provider {
     /**
@@ -306,6 +308,7 @@ interface Provider {
      * @return a {@link MiniMessage} instance
      * @since 4.10.0
      */
+    @ApiStatus.Internal
     @PlatformAPI
     @NotNull MiniMessage miniMessage();
 
@@ -315,6 +318,7 @@ interface Provider {
      * @return a {@link Consumer} modifying a {@link Builder}
      * @since 4.10.0
      */
+    @ApiStatus.Internal
     @PlatformAPI
     @NotNull Consumer<Builder> builder();
   }

diff --git a/...-gson/src/main/java/net/kyori/adventure/text/serializer/gson/GsonComponentSerializer.java b/...-gson/src/main/java/net/kyori/adventure/text/serializer/gson/GsonComponentSerializer.java
@@ -33,6 +33,7 @@
 import net.kyori.adventure.text.serializer.ComponentSerializer;
 import net.kyori.adventure.util.Buildable;
 import net.kyori.adventure.util.PlatformAPI;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
@@ -162,6 +163,7 @@ interface Builder extends AbstractBuilder<GsonComponentSerializer>, Buildable.Bu
    *
    * @since 4.8.0
    */
+  @ApiStatus.Internal
   @PlatformAPI
   interface Provider {
     /**
@@ -170,6 +172,7 @@ interface Provider {
      * @return a {@link GsonComponentSerializer}
      * @since 4.8.0
      */
+    @ApiStatus.Internal
     @PlatformAPI
     @NotNull GsonComponentSerializer gson();
 
@@ -179,6 +182,7 @@ interface Provider {
      * @return a {@link GsonComponentSerializer}
      * @since 4.8.0
      */
+    @ApiStatus.Internal
     @PlatformAPI
     @NotNull GsonComponentSerializer gsonLegacy();
 
@@ -188,6 +192,7 @@ interface Provider {
      * @return a {@link Consumer}
      * @since 4.8.0
      */
+    @ApiStatus.Internal
     @PlatformAPI
     @NotNull Consumer<Builder> builder();
   }

diff --git a/...y/src/main/java/net/kyori/adventure/text/serializer/legacy/LegacyComponentSerializer.java b/...y/src/main/java/net/kyori/adventure/text/serializer/legacy/LegacyComponentSerializer.java
@@ -35,6 +35,7 @@
 import net.kyori.adventure.text.serializer.ComponentSerializer;
 import net.kyori.adventure.util.Buildable;
 import net.kyori.adventure.util.PlatformAPI;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
@@ -271,6 +272,7 @@ interface Builder extends AbstractBuilder<LegacyComponentSerializer>, Buildable.
    *
    * @since 4.8.0
    */
+  @ApiStatus.Internal
   @PlatformAPI
   interface Provider {
     /**
@@ -279,6 +281,7 @@ interface Provider {
      * @return a {@link LegacyComponentSerializer}
      * @since 4.8.0
      */
+    @ApiStatus.Internal
     @PlatformAPI
     @NotNull LegacyComponentSerializer legacyAmpersand();
 
@@ -288,6 +291,7 @@ interface Provider {
      * @return a {@link LegacyComponentSerializer}
      * @since 4.8.0
      */
+    @ApiStatus.Internal
     @PlatformAPI
     @NotNull LegacyComponentSerializer legacySection();
 
@@ -297,6 +301,7 @@ interface Provider {
      * @return a {@link Consumer}
      * @since 4.8.0
      */
+    @ApiStatus.Internal
     @PlatformAPI
     @NotNull Consumer<Builder> legacy();
   }

diff --git a/...src/main/java/net/kyori/adventure/text/serializer/plain/PlainTextComponentSerializer.java b/...src/main/java/net/kyori/adventure/text/serializer/plain/PlainTextComponentSerializer.java
@@ -33,6 +33,7 @@
 import net.kyori.adventure.text.serializer.ComponentSerializer;
 import net.kyori.adventure.util.Buildable;
 import net.kyori.adventure.util.PlatformAPI;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
 /**
@@ -108,6 +109,7 @@ interface Builder extends AbstractBuilder<PlainTextComponentSerializer>, Buildab
    *
    * @since 4.8.0
    */
+  @ApiStatus.Internal
   @PlatformAPI
   interface Provider {
     /**
@@ -116,6 +118,7 @@ interface Provider {
      * @return a {@link PlainTextComponentSerializer}
      * @since 4.8.0
      */
+    @ApiStatus.Internal
     @PlatformAPI
     @NotNull PlainTextComponentSerializer plainTextSimple();
 
@@ -125,6 +128,7 @@ interface Provider {
      * @return a {@link Consumer}
      * @since 4.8.0
      */
+    @ApiStatus.Internal
     @PlatformAPI
     @NotNull Consumer<Builder> plainText();
   }