More v5 documentation

src/main/java/net/dv8tion/jda/api/entities/Message.java

@@ -19,7 +19,9 @@
 import net.dv8tion.jda.annotations.ReplaceWith;
 import net.dv8tion.jda.api.JDA;
 import net.dv8tion.jda.api.Permission;
+import net.dv8tion.jda.api.entities.channel.Channel;
 import net.dv8tion.jda.api.entities.channel.ChannelType;
+import net.dv8tion.jda.api.entities.channel.attribute.IThreadContainer;
 import net.dv8tion.jda.api.entities.channel.concrete.*;
 import net.dv8tion.jda.api.entities.channel.middleman.GuildMessageChannel;
 import net.dv8tion.jda.api.entities.channel.middleman.MessageChannel;
@@ -1954,7 +1956,47 @@ default MessageCreateAction replyFiles(@Nonnull Collection<? extends FileUpload>
     @Nullable
     Interaction getInteraction();
 
-    //TODO-v5: Docs
+    /**
+     * Creates a new, public {@link ThreadChannel} spawning/starting at this {@link Message} inside the {@link IThreadContainer} this message was sent in.
+     * <br>The starting message will copy this message, and will be of type {@link MessageType#THREAD_STARTER_MESSAGE MessageType.THREAD_STARTER_MESSAGE}.
+     *
+     * <p>The resulting {@link ThreadChannel ThreadChannel} may be one of:
+     * <ul>
+     *     <li>{@link ChannelType#GUILD_PUBLIC_THREAD}</li>
+     *     <li>{@link ChannelType#GUILD_NEWS_THREAD}</li>
+     * </ul>
+     *
+     * <p>Possible {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} caused by
+     * the returned {@link net.dv8tion.jda.api.requests.RestAction RestAction} include the following:
+     * <ul>
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_PERMISSIONS MISSING_PERMISSIONS}
+     *     <br>The channel could not be created due to a permission discrepancy</li>
+     *
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#MAX_CHANNELS MAX_CHANNELS}
+     *     <br>The maximum number of channels were exceeded</li>
+     *
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#THREAD_WITH_THIS_MESSAGE_ALREADY_EXISTS}
+     *     <br>This message has already been used to create a thread</li>
+     *
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#MAX_ACTIVE_THREADS}
+     *     <br>The maximum number of active threads has been reached, and no more may be created.</li>
+     * </ul>
+     *
+     * @param  name
+     *         The name of the new ThreadChannel (up to {@value Channel#MAX_NAME_LENGTH} characters)
+     *
+     * @throws IllegalArgumentException
+     *         If the provided name is null, blank, empty, or longer than {@value Channel#MAX_NAME_LENGTH} characters
+     * @throws IllegalStateException
+     *         If the message's channel is not actually a {@link net.dv8tion.jda.api.entities.channel.attribute.IThreadContainer}.
+     * @throws UnsupportedOperationException
+     *         If this is a forum channel.
+     *         You must use {@link net.dv8tion.jda.api.entities.channel.concrete.ForumChannel#createForumPost(String, MessageCreateData) createForumPost(...)} instead.
+     * @throws InsufficientPermissionException
+     *         If the bot does not have {@link net.dv8tion.jda.api.Permission#CREATE_PUBLIC_THREADS Permission.CREATE_PUBLIC_THREADS} in this channel
+     *
+     * @return A specific {@link ThreadChannelAction} that may be used to configure the new ThreadChannel before its creation.
+     */
     @CheckReturnValue
     ThreadChannelAction createThreadChannel(String name);
 

src/main/java/net/dv8tion/jda/api/entities/ThreadMember.java

@@ -22,32 +22,68 @@
 import javax.annotation.Nonnull;
 import java.time.OffsetDateTime;
 
-//TODO-v5: docs
+/**
+ * A {@link ThreadMember} represents a {@link Member Member's} participation in a Thread.
+ * <br>ThreadMembers are subscribed to {@link ThreadChannel Threads} and receive updates for them, like new message and thread changes.
+ * Only subscribed members are shown in a thread's sidebar.
+ */
 public interface ThreadMember extends IMentionable
 {
+    /**
+     * Returns the {@link net.dv8tion.jda.api.JDA JDA} instance of this thread member.
+     *
+     * @return the corresponding JDA instance
+     */
     @Nonnull
     JDA getJDA();
 
+    /**
+     * The {@link Guild} containing this {@link ThreadMember} and it's {@link ThreadChannel}.
+     *
+     * @return The {@link Guild} containing this {@link ThreadMember ThreadMembers} and it's {@link ThreadChannel}.
+     */
     @Nonnull
     Guild getGuild();
 
+    /**
+     * The {@link ThreadChannel} this thread member is subscribed to.
+     *
+     * @return The {@link ThreadChannel} this thread member is subscribed to.
+     */
     @Nonnull
     ThreadChannel getThread();
 
+    /**
+     * The {@link net.dv8tion.jda.api.entities.User User} instance
+     * <br>Shortcut for {@code getMember().getUser()}
+     *
+     * @return The User instance
+     */
     //We might not actually be able to provide a user because we only get the `userId` in the ThreadMember object.
     @Nonnull
     User getUser();
 
+    /**
+     * The corresponding {@link Member GuildMember} to this thread member.
+     *
+     * @return The corresponding {@link Member GuildMember} to this thread member.
+     */
     @Nonnull
     Member getMember();
 
+    /**
+     * The time this {@link ThreadMember} joined the subscribed {@link ThreadChannel}.
+     *
+     * @return The time this {@link ThreadMember} joined the subscribed {@link ThreadChannel}.
+     */
     @Nonnull
     OffsetDateTime getTimeJoined();
 
-    //TODO | Set<ThreadMemberFlags> getFlags();
-
-    long getFlagsRaw();
-
+    /**
+     * True, if this {@link ThreadMember} owns the subscribed {@link ThreadChannel}.
+     *
+     * @return True, if this {@link ThreadMember} owns the subscribed {@link ThreadChannel}.
+     */
     default boolean isThreadOwner()
     {
         return getThread().getOwnerIdLong() == getIdLong();

src/main/java/net/dv8tion/jda/api/entities/channel/ChannelField.java

@@ -100,13 +100,13 @@ public enum ChannelField
     DEFAULT_REACTION_EMOJI("default_reaction_emoji", AuditLogKey.CHANNEL_DEFAULT_REACTION_EMOJI),
 
     //Text Specific
-
     /**
      * The topic of the channel.
      *
-     * <p>Limited to {@link NewsChannel NewsChannels} and {@link TextChannel TextChannels}.
+     * <p>Limited to {@link NewsChannel NewsChannels}, {@link TextChannel TextChannels}, and {@link ForumChannel ForumChannels}.
      *
      * @see StandardGuildMessageChannel#getTopic()
+     * @see ForumChannel#getTopic()
      */
     TOPIC("topic", AuditLogKey.CHANNEL_TOPIC),
 
@@ -202,7 +202,7 @@ public enum ChannelField
     /**
      * The time this channel's archival information was last updated.
      *
-     * <p>This timestamp will be updated when any of the following happen:
+     * <p>This timestamp will be updated when any of the following happens:
      * <ul>
      *     <li>The channel is archived</li>
      *     <li>The channel is unarchived</li>

src/main/java/net/dv8tion/jda/api/entities/channel/attribute/IThreadContainer.java

@@ -135,12 +135,14 @@ default ThreadChannelAction createThreadChannel(@Nonnull String name)
      * </ul>
      *
      * @param  name
-     *         The name of the new ThreadChannel (up to {@value Channel#MAX_NAME_LENGTH} characters)
+     *         The name of the new ThreadChannel (up to {@value Channel#MAX_NAME_LENGTH} characters).
      * @param  isPrivate
      *         The public/private status of the new ThreadChannel. If true, the new ThreadChannel will be private.
      *
      * @throws IllegalArgumentException
-     *         If the provided name is null, blank, empty, or longer than {@value Channel#MAX_NAME_LENGTH} characters
+     *         If the provided name is null, blank, empty, or longer than {@value Channel#MAX_NAME_LENGTH} characters.
+     * @throws IllegalStateException
+     *         If the guild does have the feature flag {@code "PRIVATE_THREADS"} enabled.
      * @throws UnsupportedOperationException
      *         If this is a forum channel.
      *         You must use {@link net.dv8tion.jda.api.entities.channel.concrete.ForumChannel#createForumPost(String, MessageCreateData) createForumPost(...)} instead.

src/main/java/net/dv8tion/jda/api/entities/channel/concrete/ThreadChannel.java

@@ -97,8 +97,6 @@ default boolean isPublic()
      */
     int getMemberCount();
 
-    //TODO | This name is bad. Looking for alternatives.
-    //how about isParticipant? isThreadMember
     /**
      * Whether the currently logged in member has joined this thread.
      *

src/main/java/net/dv8tion/jda/api/events/channel/GenericChannelEvent.java

@@ -21,12 +21,19 @@
 import net.dv8tion.jda.api.entities.channel.Channel;
 import net.dv8tion.jda.api.entities.channel.ChannelType;
 import net.dv8tion.jda.api.entities.channel.middleman.GuildChannel;
+import net.dv8tion.jda.api.entities.channel.middleman.MessageChannel;
 import net.dv8tion.jda.api.entities.channel.unions.ChannelUnion;
 import net.dv8tion.jda.api.events.Event;
 
 import javax.annotation.Nonnull;
 
-//TODO-v5: Docs
+/**
+ * Top-level channel event type
+ * <br>All channel events JDA fires are derived from this class.
+ *
+ * <p>Can be used to check if an Object is a JDA event in {@link net.dv8tion.jda.api.hooks.EventListener EventListener} implementations to distinguish what event is being fired.
+ * <br>Adapter implementation: {@link net.dv8tion.jda.api.hooks.ListenerAdapter ListenerAdapter}
+ */
 public class GenericChannelEvent extends Event
 {
     protected final Channel channel;
@@ -49,17 +56,39 @@ public boolean isFromGuild()
         return getChannelType().isGuild();
     }
 
+    /**
+     * The {@link ChannelType} of the channel the event was fired from.
+     *
+     * @return The {@link ChannelType} of the channel the event was fired from.
+     */
     @Nonnull
     public ChannelType getChannelType()
     {
         return this.channel.getType();
     }
 
+    /**
+     * Used to determine if this event was received from a {@link Channel}
+     * of the {@link net.dv8tion.jda.api.entities.channel.ChannelType ChannelType} specified.
+     *
+     * <p>Useful for restricting functionality to a certain type of channels.
+     *
+     * @param  type
+     *         The {@link ChannelType ChannelType} to check against.
+     *
+     * @return True if the {@link net.dv8tion.jda.api.entities.channel.ChannelType ChannelType} which this message was received
+     *         from is the same as the one specified by {@code type}.
+     */
     public boolean isFromType(ChannelType type)
     {
         return getChannelType() == type;
     }
 
+    /**
+     * The {@link Channel} the event was fired from.
+     *
+     * @return The {@link ChannelType} of the channel the event was fired from.
+     */
     @Nonnull
     public ChannelUnion getChannel()
     {
@@ -68,7 +97,7 @@ public ChannelUnion getChannel()
 
     /**
      * The {@link net.dv8tion.jda.api.entities.Guild Guild} in which this channel event happened.
-     * <br>If this channel event was not received in a {@link net.dv8tion.jda.api.entities.channel.concrete.TextChannel TextChannel},
+     * <br>If this channel event was not received in a {@link net.dv8tion.jda.api.entities.channel.middleman.GuildChannel GuildChannel},
      * this will throw an {@link java.lang.IllegalStateException}.
      *
      * @throws java.lang.IllegalStateException
@@ -86,6 +115,4 @@ public Guild getGuild()
             throw new IllegalStateException("This channel event did not happen in a guild");
         return ((GuildChannel) channel).getGuild();
     }
-
-    //TODO-v5: Add getters for all channel types
 }

src/main/java/net/dv8tion/jda/api/events/channel/update/ChannelUpdateAppliedTagsEvent.java

@@ -18,6 +18,7 @@
 
 import net.dv8tion.jda.api.JDA;
 import net.dv8tion.jda.api.entities.channel.ChannelField;
+import net.dv8tion.jda.api.entities.channel.concrete.ForumChannel;
 import net.dv8tion.jda.api.entities.channel.concrete.ThreadChannel;
 import net.dv8tion.jda.api.entities.channel.forums.ForumTag;
 import net.dv8tion.jda.api.utils.cache.SortedSnowflakeCacheView;
@@ -31,13 +32,20 @@
 /**
  * Indicates that the tags applied to a {@link ThreadChannel forum post thread} have been updated.
  *
+ * <p>Limited to {@link ThreadChannel ThreadChannels} inside {@link ForumChannel ForumChannels}
+ *
+ * @see ThreadChannel#getAppliedTags()
  * @see ChannelField#APPLIED_TAGS
  */
 public class ChannelUpdateAppliedTagsEvent extends GenericChannelUpdateEvent<List<Long>>
 {
+
+    public static final ChannelField FIELD = ChannelField.APPLIED_TAGS;
+    public static final String IDENTIFIER = FIELD.getFieldName();
+
     public ChannelUpdateAppliedTagsEvent(@Nonnull JDA api, long responseNumber, @Nonnull ThreadChannel channel, @Nonnull List<Long> oldValue, @Nonnull List<Long> newValue)
     {
-        super(api, responseNumber, channel, ChannelField.APPLIED_TAGS, oldValue, newValue);
+        super(api, responseNumber, channel, FIELD, oldValue, newValue);
     }
 
     /**

src/main/java/net/dv8tion/jda/api/events/channel/update/ChannelUpdateArchiveTimestampEvent.java

@@ -19,15 +19,31 @@
 import net.dv8tion.jda.api.JDA;
 import net.dv8tion.jda.api.entities.channel.Channel;
 import net.dv8tion.jda.api.entities.channel.ChannelField;
+import net.dv8tion.jda.api.entities.channel.concrete.ThreadChannel;
 import net.dv8tion.jda.internal.utils.Helpers;
 
 import javax.annotation.Nonnull;
 import java.time.OffsetDateTime;
 
-//TODO-v5: Docs
+/**
+ * Indicates that a {@link Channel} archival timestamp was updated.
+ *
+ * <p>This timestamp will be updated when any of the following happens:
+ * <ul>
+ *     <li>The channel is archived</li>
+ *     <li>The channel is unarchived</li>
+ *     <li>The AUTO_ARCHIVE_DURATION is changed.</li>
+ * </ul>
+ *
+ * Limited to {@link ThreadChannel Thread Channels}.
+ *
+ * @see ThreadChannel#getTimeArchiveInfoLastModified()
+ * @see ChannelField#ARCHIVED_TIMESTAMP
+ */
 public class ChannelUpdateArchiveTimestampEvent extends GenericChannelUpdateEvent<OffsetDateTime>
 {
     public static final ChannelField FIELD = ChannelField.ARCHIVED_TIMESTAMP;
+    public static final String IDENTIFIER = FIELD.getFieldName();
 
     private final long oldTimestamp;
     private final long newTimestamp;

src/main/java/net/dv8tion/jda/api/events/channel/update/ChannelUpdateArchivedEvent.java

@@ -19,13 +19,22 @@
 import net.dv8tion.jda.api.JDA;
 import net.dv8tion.jda.api.entities.channel.Channel;
 import net.dv8tion.jda.api.entities.channel.ChannelField;
+import net.dv8tion.jda.api.entities.channel.concrete.ThreadChannel;
 
 import javax.annotation.Nonnull;
 
-//TODO-v5: Docs
+/**
+ * Indicates that a {@link Channel Channels} archived-state has been updated.
+ *
+ * <p>Limited to {@link ThreadChannel Thread Channels}.
+ *
+ * @see ThreadChannel#isArchived()
+ * @see ChannelField#ARCHIVED
+ */
 public class ChannelUpdateArchivedEvent extends GenericChannelUpdateEvent<Boolean>
 {
     public static final ChannelField FIELD = ChannelField.ARCHIVED;
+    public static final String IDENTIFIER = FIELD.getFieldName();
 
     public ChannelUpdateArchivedEvent(@Nonnull JDA api, long responseNumber, Channel channel, Boolean oldValue, Boolean newValue)
     {

src/main/java/net/dv8tion/jda/api/events/channel/update/ChannelUpdateAutoArchiveDurationEvent.java

@@ -23,10 +23,19 @@
 
 import javax.annotation.Nonnull;
 
-//TODO-v5: Docs
+/**
+ * Indicates that a {@link Channel Channels} auto archive duration has been updated.
+ *
+ * <p>Limited to {@link ThreadChannel Thread Channels}.
+ *
+ * @see ThreadChannel#getAutoArchiveDuration()
+ * @see ThreadChannel.AutoArchiveDuration
+ * @see ChannelField#AUTO_ARCHIVE_DURATION
+ */
 public class ChannelUpdateAutoArchiveDurationEvent extends GenericChannelUpdateEvent<ThreadChannel.AutoArchiveDuration>
 {
     public static final ChannelField FIELD = ChannelField.AUTO_ARCHIVE_DURATION;
+    public static final String IDENTIFIER = FIELD.getFieldName();
 
     public ChannelUpdateAutoArchiveDurationEvent(@Nonnull JDA api, long responseNumber, Channel channel, ThreadChannel.AutoArchiveDuration oldValue, ThreadChannel.AutoArchiveDuration newValue)
     {

src/main/java/net/dv8tion/jda/api/events/channel/update/ChannelUpdateBitrateEvent.java

@@ -19,13 +19,22 @@
 import net.dv8tion.jda.api.JDA;
 import net.dv8tion.jda.api.entities.channel.Channel;
 import net.dv8tion.jda.api.entities.channel.ChannelField;
+import net.dv8tion.jda.api.entities.channel.middleman.AudioChannel;
 
 import javax.annotation.Nonnull;
 
-//TODO-v5: Docs
+/**
+ * Indicates that a {@link Channel Channels} bitrate has been updated.
+ *
+ * <p>Limited to {@link AudioChannel Audio Channels}.
+ *
+ * @see AudioChannel#getBitrate()
+ * @see ChannelField#BITRATE
+ */
 public class ChannelUpdateBitrateEvent extends GenericChannelUpdateEvent<Integer>
 {
     public static final ChannelField FIELD = ChannelField.BITRATE;
+    public static final String IDENTIFIER = FIELD.getFieldName();
 
     public ChannelUpdateBitrateEvent(@Nonnull JDA api, long responseNumber, Channel channel, Integer oldValue, Integer newValue)
     {