Rework annotation documentation

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.
+ * <br>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

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.
+ * <br>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

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

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.
  *
- * <p>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.
+ * <p>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.
  * <br>Assuming the cache policy allows a member to be cached, the member will be loaded in the cache when either:
  * <ul>
- *     <li>JDA loads it on startup, using {@link ChunkingFilter}</li>
- *     <li>It is loaded explicitly, using {@link Guild#retrieveMemberById(long)} for example</li>
- *     <li>An event from the member is received, such as {@link SlashCommandInteractionEvent} for example</li>
+ *     <li>JDA loads it on startup, if a {@link ChunkingFilter} is configured</li>
+ *     <li>It is loaded explicitly, for example, using {@link Guild#retrieveMemberById(long)}</li>
+ *     <li>An event containing a member is received, such as {@link SlashCommandInteractionEvent}</li>
  * </ul>
  *
  * @see MemberCachePolicy
  * @see ChunkingFilter
+ * @see JDABuilder#setMemberCachePolicy(MemberCachePolicy)
+ * @see JDABuilder#setChunkingFilter(ChunkingFilter)
  */
 @Target({ElementType.TYPE, ElementType.METHOD})
 @Retention(RetentionPolicy.RUNTIME)