From 99a673c1154d7f2e9d5258aa506f7c94fa1a5285 Mon Sep 17 00:00:00 2001 From: freya02 <41875020+freya022@users.noreply.github.com> Date: Sun, 21 Jan 2024 13:01:31 +0100 Subject: [PATCH] Rework annotation documentation --- .../events/annotations/RequiredCacheFlags.java | 7 +++++-- .../api/events/annotations/RequiredIntents.java | 7 +++++-- .../events/annotations/RequiredPermissions.java | 7 +++++-- .../annotations/RequiresCachedMember.java | 17 +++++++++++------ 4 files changed, 26 insertions(+), 12 deletions(-) diff --git a/src/main/java/net/dv8tion/jda/api/events/annotations/RequiredCacheFlags.java b/src/main/java/net/dv8tion/jda/api/events/annotations/RequiredCacheFlags.java index e83ef8d85d6..37b7b51e817 100644 --- a/src/main/java/net/dv8tion/jda/api/events/annotations/RequiredCacheFlags.java +++ b/src/main/java/net/dv8tion/jda/api/events/annotations/RequiredCacheFlags.java @@ -16,17 +16,20 @@ package net.dv8tion.jda.api.events.annotations; +import net.dv8tion.jda.api.JDABuilder; import net.dv8tion.jda.api.utils.cache.CacheFlag; import java.lang.annotation.*; /** - * Annotation used by events and {@link CacheFlag#fromEvents(Class[])} + * Annotates the required cache flags for this event. + *
This is used by {@link CacheFlag#fromEvents(Class[])} * to determine which cache flags are required and/or optional for a given event type. * * @see CacheFlag#fromEvents(Class[]) + * @see JDABuilder#enableCache(CacheFlag, CacheFlag...) */ -@Target({ElementType.TYPE, ElementType.METHOD}) +@Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME) @Documented public @interface RequiredCacheFlags diff --git a/src/main/java/net/dv8tion/jda/api/events/annotations/RequiredIntents.java b/src/main/java/net/dv8tion/jda/api/events/annotations/RequiredIntents.java index 8b1b519204f..17d259b6dfa 100644 --- a/src/main/java/net/dv8tion/jda/api/events/annotations/RequiredIntents.java +++ b/src/main/java/net/dv8tion/jda/api/events/annotations/RequiredIntents.java @@ -16,17 +16,20 @@ package net.dv8tion.jda.api.events.annotations; +import net.dv8tion.jda.api.JDABuilder; import net.dv8tion.jda.api.requests.GatewayIntent; import java.lang.annotation.*; /** - * Annotation used by events and {@link GatewayIntent#fromEvents(Class[])} + * Annotates the required intents for this event. + *
This is used by {@link GatewayIntent#fromEvents(Class[])} * to determine which intents are required and/or optional for a given event type. * * @see GatewayIntent#fromEvents(Class[]) + * @see JDABuilder#enableIntents(GatewayIntent, GatewayIntent...) */ -@Target({ElementType.TYPE, ElementType.METHOD}) +@Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME) @Documented public @interface RequiredIntents diff --git a/src/main/java/net/dv8tion/jda/api/events/annotations/RequiredPermissions.java b/src/main/java/net/dv8tion/jda/api/events/annotations/RequiredPermissions.java index fc90166cee7..15f326c742d 100644 --- a/src/main/java/net/dv8tion/jda/api/events/annotations/RequiredPermissions.java +++ b/src/main/java/net/dv8tion/jda/api/events/annotations/RequiredPermissions.java @@ -17,15 +17,18 @@ package net.dv8tion.jda.api.events.annotations; import net.dv8tion.jda.api.Permission; +import net.dv8tion.jda.api.entities.IPermissionHolder; +import net.dv8tion.jda.api.entities.channel.middleman.GuildChannel; import java.lang.annotation.*; /** - * Annotation used by events to determine which permissions are required and/or optional for a given event type. + * Annotates the required and/or optional permissions on this event. * * @see Permission + * @see IPermissionHolder#hasPermission(GuildChannel, Permission...) */ -@Target({ElementType.TYPE, ElementType.METHOD}) +@Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME) @Documented public @interface RequiredPermissions diff --git a/src/main/java/net/dv8tion/jda/api/events/annotations/RequiresCachedMember.java b/src/main/java/net/dv8tion/jda/api/events/annotations/RequiresCachedMember.java index f3ae6674abc..51a0d7c60f2 100644 --- a/src/main/java/net/dv8tion/jda/api/events/annotations/RequiresCachedMember.java +++ b/src/main/java/net/dv8tion/jda/api/events/annotations/RequiresCachedMember.java @@ -16,27 +16,32 @@ package net.dv8tion.jda.api.events.annotations; +import net.dv8tion.jda.api.JDABuilder; import net.dv8tion.jda.api.entities.Guild; import net.dv8tion.jda.api.events.interaction.command.SlashCommandInteractionEvent; +import net.dv8tion.jda.api.requests.GatewayIntent; import net.dv8tion.jda.api.utils.ChunkingFilter; import net.dv8tion.jda.api.utils.MemberCachePolicy; import java.lang.annotation.*; /** - * Annotation used by events, specifying that a cached member is required for the event to fire for said member. + * Annotates this event as requiring a cached member to fire, + * or a method requiring a cached member to return appropriate results. * - *

There are multiple ways a member/user would be cached, - * the prerequisite being that the {@link MemberCachePolicy} needs to allow it to be cached first. + *

For a member/user to be cached, {@link GatewayIntent#GUILD_MEMBERS GatewayIntent.GUILD_MEMBERS} needs to be enabled, + * and the {@link MemberCachePolicy} configured to allow some, if not all, members to be cached. *
Assuming the cache policy allows a member to be cached, the member will be loaded in the cache when either: *

* * @see MemberCachePolicy * @see ChunkingFilter + * @see JDABuilder#setMemberCachePolicy(MemberCachePolicy) + * @see JDABuilder#setChunkingFilter(ChunkingFilter) */ @Target({ElementType.TYPE, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME)