diff --git a/api/src/main/java/net/kyori/adventure/bossbar/HackyBossBarPlatformBridge.java b/api/src/main/java/net/kyori/adventure/bossbar/HackyBossBarPlatformBridge.java
index fa482d72c4..07c7734251 100644
--- a/api/src/main/java/net/kyori/adventure/bossbar/HackyBossBarPlatformBridge.java
+++ b/api/src/main/java/net/kyori/adventure/bossbar/HackyBossBarPlatformBridge.java
@@ -24,6 +24,7 @@
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
@@ -31,6 +32,7 @@
*
* @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
index 1cc714ef98..6523158196 100644
--- a/api/src/main/java/net/kyori/adventure/util/PlatformAPI.java
+++ b/api/src/main/java/net/kyori/adventure/util/PlatformAPI.java
@@ -23,6 +23,7 @@
*/
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;
@@ -30,13 +31,17 @@
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.
+ *
+ *
This annotation should always be used in tandem with the {@link ApiStatus.Internal} annotation to more consistently produce
+ * warnings
*
* @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
index c49ade6d62..55262d44cd 100644
--- 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 {
* @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();
}
diff --git a/text-serializer-gson/src/main/java/net/kyori/adventure/text/serializer/gson/GsonComponentSerializer.java b/text-serializer-gson/src/main/java/net/kyori/adventure/text/serializer/gson/GsonComponentSerializer.java
index 40bc90ea36..838e2d8d04 100644
--- a/text-serializer-gson/src/main/java/net/kyori/adventure/text/serializer/gson/GsonComponentSerializer.java
+++ b/text-serializer-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, 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();
}
diff --git a/text-serializer-legacy/src/main/java/net/kyori/adventure/text/serializer/legacy/LegacyComponentSerializer.java b/text-serializer-legacy/src/main/java/net/kyori/adventure/text/serializer/legacy/LegacyComponentSerializer.java
index ab630eae7c..4f2294c235 100644
--- a/text-serializer-legacy/src/main/java/net/kyori/adventure/text/serializer/legacy/LegacyComponentSerializer.java
+++ b/text-serializer-legacy/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, 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 legacy();
}
diff --git a/text-serializer-plain/src/main/java/net/kyori/adventure/text/serializer/plain/PlainTextComponentSerializer.java b/text-serializer-plain/src/main/java/net/kyori/adventure/text/serializer/plain/PlainTextComponentSerializer.java
index b39e014525..87b027a18f 100644
--- a/text-serializer-plain/src/main/java/net/kyori/adventure/text/serializer/plain/PlainTextComponentSerializer.java
+++ b/text-serializer-plain/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, 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 plainText();
}