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(); }