From 2c636c5ac6d68526616c7e892a5c8e5a7cc3fd7d Mon Sep 17 00:00:00 2001 From: Luck Date: Thu, 4 Mar 2021 00:25:11 +0000 Subject: [PATCH] Further javadoc improvements --- api/build.gradle | 1 + api/javadoc/overview.html | 19 ++++++++++ .../net/luckperms/api/LuckPermsProvider.java | 37 +++++++++++++++---- .../luckperms/api/context/ContextManager.java | 2 +- .../net/luckperms/api/context/ContextSet.java | 2 +- .../api/context/ImmutableContextSet.java | 2 +- .../api/model/group/GroupManager.java | 2 +- .../luckperms/api/model/user/UserManager.java | 2 +- .../java/net/luckperms/api/node/HeldNode.java | 1 + 9 files changed, 55 insertions(+), 13 deletions(-) create mode 100644 api/javadoc/overview.html diff --git a/api/build.gradle b/api/build.gradle index 907d95472..f40472100 100644 --- a/api/build.gradle +++ b/api/build.gradle @@ -13,6 +13,7 @@ if (project.hasProperty('sonatypeUsername') && project.hasProperty('sonatypePass javadoc { title = 'LuckPerms API (v' + project.ext.apiVersion + ')' + options.overview = 'javadoc/overview.html' options.encoding = 'UTF-8' options.charSet = 'UTF-8' options.links( diff --git a/api/javadoc/overview.html b/api/javadoc/overview.html new file mode 100644 index 000000000..061a300b6 --- /dev/null +++ b/api/javadoc/overview.html @@ -0,0 +1,19 @@ + +

+ LuckPerms is a permissions plugin for Minecraft servers. It allows server admins to control what + features players can use by creating groups and assigning permissions. +

+

Useful Links

+ +

Maven

+

+ The API artifact is deployed to Maven Central under + + group id: net.luckperms, artifact id: api. + +

+ \ No newline at end of file diff --git a/api/src/main/java/net/luckperms/api/LuckPermsProvider.java b/api/src/main/java/net/luckperms/api/LuckPermsProvider.java index c1e09c4cf..193242d1e 100644 --- a/api/src/main/java/net/luckperms/api/LuckPermsProvider.java +++ b/api/src/main/java/net/luckperms/api/LuckPermsProvider.java @@ -27,41 +27,62 @@ package net.luckperms.api; import org.checkerframework.checker.nullness.qual.NonNull; +import static org.jetbrains.annotations.ApiStatus.Internal; + /** - * Provides static access to the {@link LuckPerms} service. + * Provides static access to the {@link LuckPerms} API. * *

Ideally, the ServiceManager for the platform should be used to obtain an - * instance, however, this provider can be used if you need static access.

+ * instance, however, this provider can be used if this is not viable.

*/ public final class LuckPermsProvider { private static LuckPerms instance = null; /** - * Gets an instance of the {@link LuckPerms} service, - * throwing {@link IllegalStateException} if an instance is not yet loaded. + * Gets an instance of the {@link LuckPerms} API, + * throwing {@link IllegalStateException} if the API is not loaded yet. * - *

Will never return null.

+ *

This method will never return null.

* - * @return an api instance - * @throws IllegalStateException if the api is not loaded + * @return an instance of the LuckPerms API + * @throws IllegalStateException if the API is not loaded yet */ public static @NonNull LuckPerms get() { if (instance == null) { - throw new IllegalStateException("The LuckPerms API is not loaded."); + throw new NotLoadedException(); } return instance; } + @Internal static void register(LuckPerms instance) { LuckPermsProvider.instance = instance; } + @Internal static void unregister() { LuckPermsProvider.instance = null; } + @Internal private LuckPermsProvider() { throw new UnsupportedOperationException("This class cannot be instantiated."); } + /** + * Exception thrown when the API is requested before it has been loaded. + */ + private static final class NotLoadedException extends IllegalStateException { + private static final String MESSAGE = "The LuckPerms API isn't loaded yet!\n" + + "This could be because:\n" + + " a) the LuckPerms plugin is not installed or it failed to enable\n" + + " b) your plugin does not declare a dependency on LuckPerms\n" + + " c) you are attempting to use the API before plugins reach the 'enable' phase\n" + + " (call the #get method in onEnable, not in your plugin constructor!)\n"; + + NotLoadedException() { + super(MESSAGE); + } + } + } diff --git a/api/src/main/java/net/luckperms/api/context/ContextManager.java b/api/src/main/java/net/luckperms/api/context/ContextManager.java index d20229aa5..5a6d929f9 100644 --- a/api/src/main/java/net/luckperms/api/context/ContextManager.java +++ b/api/src/main/java/net/luckperms/api/context/ContextManager.java @@ -165,7 +165,7 @@ public interface ContextManager { * Invalidates the lookup cache for a given subject * * @param subject the subject - * @deprecated use {@link #signalContextUpdate(Object)} + * @deprecated Use {@link #signalContextUpdate(Object)} instead */ @Deprecated default void invalidateCache(@NonNull Object subject) { diff --git a/api/src/main/java/net/luckperms/api/context/ContextSet.java b/api/src/main/java/net/luckperms/api/context/ContextSet.java index cec8306ca..bb4e0d157 100644 --- a/api/src/main/java/net/luckperms/api/context/ContextSet.java +++ b/api/src/main/java/net/luckperms/api/context/ContextSet.java @@ -136,7 +136,7 @@ public interface ContextSet extends Iterable { * may not be a true representation of the set.

* * @return an immutable map - * @deprecated because the resultant map may not contain all data in the ContextSet + * @deprecated Deprecated because the returned map may not contain all data in the ContextSet */ @Deprecated @NonNull @Unmodifiable Map toFlattenedMap(); diff --git a/api/src/main/java/net/luckperms/api/context/ImmutableContextSet.java b/api/src/main/java/net/luckperms/api/context/ImmutableContextSet.java index bbb8c260a..b2312fa52 100644 --- a/api/src/main/java/net/luckperms/api/context/ImmutableContextSet.java +++ b/api/src/main/java/net/luckperms/api/context/ImmutableContextSet.java @@ -67,7 +67,7 @@ public interface ImmutableContextSet extends ContextSet { } /** - * @deprecated Already immutable! + * @deprecated This context set is already immutable! */ @Override @Deprecated diff --git a/api/src/main/java/net/luckperms/api/model/group/GroupManager.java b/api/src/main/java/net/luckperms/api/model/group/GroupManager.java index 5f995c82e..551a3bbfe 100644 --- a/api/src/main/java/net/luckperms/api/model/group/GroupManager.java +++ b/api/src/main/java/net/luckperms/api/model/group/GroupManager.java @@ -147,7 +147,7 @@ public interface GroupManager { * @param permission the permission to search for * @return a list of held permissions, or null if the operation failed * @throws NullPointerException if the permission is null - * @deprecated use {@link #searchAll(NodeMatcher)} + * @deprecated Use {@link #searchAll(NodeMatcher)} instead */ @Deprecated @NonNull CompletableFuture<@Unmodifiable List>> getWithPermission(@NonNull String permission); diff --git a/api/src/main/java/net/luckperms/api/model/user/UserManager.java b/api/src/main/java/net/luckperms/api/model/user/UserManager.java index 06a678418..d58336a0c 100644 --- a/api/src/main/java/net/luckperms/api/model/user/UserManager.java +++ b/api/src/main/java/net/luckperms/api/model/user/UserManager.java @@ -184,7 +184,7 @@ public interface UserManager { * @param permission the permission to search for * @return a list of held permissions * @throws NullPointerException if the permission is null - * @deprecated use {@link #searchAll(NodeMatcher)} + * @deprecated Use {@link #searchAll(NodeMatcher)} instead */ @Deprecated @NonNull CompletableFuture<@Unmodifiable List>> getWithPermission(@NonNull String permission); diff --git a/api/src/main/java/net/luckperms/api/node/HeldNode.java b/api/src/main/java/net/luckperms/api/node/HeldNode.java index fd5439d7f..55d2754d7 100644 --- a/api/src/main/java/net/luckperms/api/node/HeldNode.java +++ b/api/src/main/java/net/luckperms/api/node/HeldNode.java @@ -33,6 +33,7 @@ import org.checkerframework.checker.nullness.qual.NonNull; * A relationship between a {@link PermissionHolder} and a {@link Node}. * * @param the identifier type of the holder + * @deprecated The only usages of this interface are also deprecated. */ @Deprecated public interface HeldNode {