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. +
+
+ The API artifact is deployed to Maven Central under
+
+ group id: net.luckperms
, artifact id: 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