Some documentation on //todo-v5: docs

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

@@ -22,7 +22,26 @@
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
-//TODO-v5: Docs
+/**
+ * Represents a Guild Channel that is capable of handling audio.
+ * <br>This is a {@link GuildChannel GuildChannel} that contains additional methods present for audio channels
+ *
+ * @see VoiceChannel
+ * @see StageChannel
+ *
+ * @see   Guild#getVoiceChannelCache()
+ * @see   Guild#getVoiceChannels()
+ * @see   Guild#getVoiceChannelsByName(String, boolean)
+ * @see   Guild#getVoiceChannelById(long)
+ *
+ * @see   Guild#getStageChannelCache()
+ * @see   Guild#getStageChannels()
+ * @see   Guild#getStageChannelsByName(String, boolean)
+ * @see   Guild#getStageChannelById(long)
+ *
+ * @see net.dv8tion.jda.api.JDA#getVoiceChannelById(long)
+ * @see net.dv8tion.jda.api.JDA#getStageChannelById(long)
+ */
 public interface AudioChannel extends GuildChannel, IMemberContainer
 {
     //TODO-v5: Docs

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

@@ -11,7 +11,15 @@
 import javax.annotation.Nullable;
 import java.util.List;
 
-//TODO-v5: Docs
+
+/**
+ * Represents a standard {@link Guild Guild} {@link MessageChannel MessageChannels}.
+ * <br>These are the "<i>normal</i>" message channels, and do not include Threads.
+ *
+ * @see net.dv8tion.jda.api.entities.GuildMessageChannel
+ * @see TextChannel
+ * @see NewsChannel
+ */
 public interface BaseGuildMessageChannel extends GuildMessageChannel, IThreadContainer, GuildChannel, ICategorizableChannel, ICopyableChannel, IPermissionContainer, IMemberContainer, IInviteContainer, IPositionableChannel
 {
     //TODO-v5: Docs

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

@@ -21,35 +21,175 @@
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
-//TODO-v5: Needs docs
+
+/**
+ * This enum represents the attributes of a channel that can be modified by events.
+ * <br><b>Most</b> of these changes are tracked and reflected by {@link AuditLogKey Audit Log Entries}.
+ *
+ * @see net.dv8tion.jda.api.events.channel.GenericChannelEvent
+ * @see AuditLogKey
+ */
 public enum ChannelField
 {
     //TODO-v5: Should these be the REST JSON names (camelCase), the AuditLogKey names (snake_case), or JDA's generic naming (Event.IDENTIFIER)
     //TODO-v5: Current using JDA's generic namings
 
-    //TODO-v5: All of these need explicit docs
+    //Generic
+
+    /**
+     * The {@link ChannelType type} of the channel.
+     *
+     * @see Channel#getType()
+     */
     TYPE("type", AuditLogKey.CHANNEL_TYPE),
+
+    /**
+     * The name of the channel.
+     *
+     * @see Channel#getName()
+     */
     NAME("name", AuditLogKey.CHANNEL_NAME),
 
+    /**
+     * The {@link Category parent} of the channel.
+     *
+     * Limited to {@link BaseGuildMessageChannel Base Guild Channels} (and implementations).
+     *
+     * @see BaseGuildMessageChannel#getParentCategory()
+     */
+    PARENT("parent", AuditLogKey.CHANNEL_PARENT),
+
+    /**
+     * The position of this channel relative to other channels in the guild.
+     *
+     * @see IPositionableChannel#getPosition()
+     * //todo-v5 if the calculation of IPositionableChannel#getPosition() changes, this may need modification too.
+     */
     POSITION("position", null), //Discord doesn't track Channel position changes in AuditLog.
 
+
+    //Text Specific
+
+    /**
+     * The topic of the channel.
+     *
+     * Limited to {@link BaseGuildMessageChannel Base Guild Channels} (and implementations).
+     *
+     * @see BaseGuildMessageChannel#getTopic()
+     */
     TOPIC("topic", AuditLogKey.CHANNEL_TOPIC),
+
+    /**
+     * The NSFW state of the channel.
+     *
+     * Limited to {@link BaseGuildMessageChannel Base Guild Channels} (and implementations).
+     *
+     * @see BaseGuildMessageChannel#isNSFW()
+     */
     NSFW("nsfw", AuditLogKey.CHANNEL_NSFW),
+
+    /**
+     * The state of slow mode in the channel.  This defines the minimum time between message sends.
+     *
+     * Limited to {@link TextChannel Text Channels}.
+     *
+     * @see TextChannel#getSlowmode()
+     */
     SLOWMODE("slowmode", AuditLogKey.CHANNEL_SLOWMODE),
 
-    PARENT("parent", AuditLogKey.CHANNEL_PARENT),
 
+    //Voice Specific
+
+    /**
+     * The bitrate (in bits per second) of the audio in this channel.
+     *
+     * For standard channels this is between 8000 and 96000.
+     *
+     * VIP servers extend this limit to 128000.
+     *
+     * Limited to {@link AudioChannel Audio Channels}.
+     *
+     * @see AudioChannel#getBitrate()
+     */
     BITRATE("bitrate", AuditLogKey.CHANNEL_BITRATE),
+
+    /**
+     * The region of the channel.
+     *
+     * Limited to {@link AudioChannel Audio Channels}.
+     *
+     * @see AudioChannel#getRegion()
+     * @see net.dv8tion.jda.api.Region
+     */
     REGION("region", null), //TODO-v5: JDA needs to add support for channel-specific audit log tracking
+
+    /**
+     * The maximum user count of this channel.
+     *
+     * Limited to {@link VoiceChannel Voice Channels}.
+     *
+     * @see VoiceChannel#getUserLimit()
+     */
     USER_LIMIT("userlimit", AuditLogKey.CHANNEL_USER_LIMIT),
 
+
     //Thread Specific
+
+    /**
+     * The auto archive duration of this channel.
+     *
+     * If the thread is inactive for this long, it becomes auto-archived.
+     *
+     * Limited to {@link ThreadChannel Thread Channels}.
+     *
+     * @see ThreadChannel#getAutoArchiveDuration()
+     */
     AUTO_ARCHIVE_DURATION("autoArchiveDuration", AuditLogKey.THREAD_AUTO_ARCHIVE_DURATION),
+
+    /**
+     * The archive state of this channel.
+     *
+     * If the channel is archived, this is true.
+     *
+     * Limited to {@link ThreadChannel Thread Channels}.
+     *
+     * @see ThreadChannel#isArchived()
+     */
     ARCHIVED("archived", AuditLogKey.THREAD_ARCHIVED),
+
+    /**
+     * The archive time of this channel.
+     *
+     * If the channel is archived, this timestamp will be when it was archived.
+     *
+     * Limited to {@link ThreadChannel Thread Channels}.
+     *
+     * //todo-v5: Docs - check if this is actually correct
+     * @see ThreadChannel#getTimeArchiveInfoLastModified()
+     */
     ARCHIVED_TIMESTAMP("archiveTimestamp", null),
+
+    /**
+     * The locked state of this channel.
+     *
+     * If the channel is locked, this is true.
+     *
+     * Limited to {@link ThreadChannel Thread Channels}.
+     *
+     * @see ThreadChannel#isLocked() ()
+     */
     LOCKED("locked", AuditLogKey.THREAD_LOCKED),
-    INVITABLE("invitable", AuditLogKey.THREAD_INVITABLE)
 
+    /**
+     * The invite state of this channel.
+     *
+     * If the channel is invitable, this is true.
+     *
+     * Limited to {@link ThreadChannel Thread Channels}.
+     *
+     * @see ThreadChannel#isInvitable()
+     */
+    INVITABLE("invitable", AuditLogKey.THREAD_INVITABLE)
     ;
 
     private final String fieldName;

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

@@ -11,7 +11,15 @@
 import java.util.List;
 import java.util.stream.Collectors;
 
-//TODO-v5: Docs
+
+/**
+ * Represents all message channels present in guilds.
+ *
+ * This includes channels that are not included in {@link BaseGuildMessageChannel BaseGuildMessageChannel}, such as Threads.
+ *
+ * @see BaseGuildMessageChannel
+ * //todo-v5: Add links to MessageThreads
+ */
 public interface GuildMessageChannel extends GuildChannel, MessageChannel
 {
     /**

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

@@ -21,18 +21,31 @@
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
-//TODO-v5: Need Docs
+
+/**
+ * Represents a channel that can be a member of a {@link Category}.
+ * Channels represented by this interface can have a parent {@link Category}.
+ *
+ * @see Category
+ * @see Guild#getCategories()
+ */
 public interface ICategorizableChannel extends GuildChannel, IPermissionContainer
 {
     //TODO-v5: Docs
     @Override
     @Nonnull
     ICategorizableChannelManager<?, ?> getManager();
 
-    //TODO-v5: Docs
+    /**
+     * Get the snowflake of the {@link Category} that contains this channel.
+     * @return The Discord ID snowflake of the parent channel as a long.
+     */
     long getParentCategoryIdLong();
 
-    //TODO-v5: Docs
+    /**
+     * Get the snowflake of the {@link Category} that contains this channel.
+     * @return The Discord ID snowflake of the parent channel as a String.
+     */
     default String getParentCategoryId()
     {
         return Long.toUnsignedString(getParentCategoryIdLong());

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

@@ -21,7 +21,12 @@
 import javax.annotation.CheckReturnValue;
 import javax.annotation.Nonnull;
 
-//TODO-v5: Need Docs
+
+/**
+ * Represents a GuildChannel that is capable of being copied.
+ *
+ * Please see {@link ICopyableChannel#createCopy()} for information on what is copied.
+ */
 public interface ICopyableChannel extends GuildChannel
 {
     /**

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

@@ -23,7 +23,11 @@
 import javax.annotation.Nonnull;
 import java.util.List;
 
-//TODO-v5: Need Docs
+/**
+ * Represents a {@link GuildChannel GuildChannel} that can be the target of a Guild's invite.
+ *
+ * Invites have to be targeted at exactly one {@link IInviteContainer}, which will open when the invite is used (unless restricted by permissions).
+ */
 public interface IInviteContainer extends GuildChannel
 {
     /**

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

@@ -19,7 +19,13 @@
 import javax.annotation.Nonnull;
 import java.util.List;
 
-//TODO-v5: Need Docs
+/**
+ * Represents a {@link GuildChannel} that is capable of containing members.
+ *
+ * Implementations interpret this meaning as best applies to them.
+ *
+ * @see IMemberContainer#getMembers()
+ */
 public interface IMemberContainer extends GuildChannel
 {
     /**

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

@@ -27,7 +27,11 @@
 import java.util.List;
 import java.util.stream.Collectors;
 
-//TODO-v5: Need Docs
+/**
+ * Represents a {@link GuildChannel} that is capable of holding {@link PermissionOverride Permission Overrides}.
+ *
+ * @see PermissionOverride
+ */
 public interface IPermissionContainer extends GuildChannel
 {
     //TODO-v5: Docs

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

@@ -22,7 +22,13 @@
 import java.util.List;
 import java.util.stream.Collectors;
 
-//TODO-v5: Need Docs
+/**
+ * Represents a {@link GuildChannel GuildChannel} that has a position.
+ *
+ * These channels can be re-ordered using a position value.
+ *
+ * In the case of identical permission values, the natural ordering of the channel snowflakes are used.
+ */
 public interface IPositionableChannel extends GuildChannel
 {
     //TODO-v5: Docs

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

@@ -13,7 +13,19 @@
 import javax.annotation.CheckReturnValue;
 import javax.annotation.Nonnull;
 
-//TODO-v5: Docs
+/**
+ * Represents {@link BaseGuildMessageChannel} that are News Channels.
+ *
+ * The Discord client may refer to these as Announcement Channels.
+ *
+ * Members can subscribe channels in their own guilds to receive messages crossposted from this channel.
+ * This is referred to as following this channel.
+ *
+ * Messages sent in this channel can be crossposted, at which point they will be sent (via webhook) to all subscribed channels.
+ *
+ * @see Message#getFlags()
+ * @see net.dv8tion.jda.api.entities.Message.MessageFlag#CROSSPOSTED
+ */
 public interface NewsChannel extends BaseGuildMessageChannel
 {
     /**

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

@@ -22,15 +22,15 @@
 import javax.annotation.Nonnull;
 
 /**
- * Represents a Discord Text GuildChannel.
- * <br>Adds additional functionality and information for text channels in Discord.
+ * Represents a standard Discord Text GuildChannel.
+ * <br>Adds additional functionality and information for text channels in Discord,
+ * on top of the common functionality present in other guild message channels.
  *
  * <p>This is a {@link GuildChannel GuildChannel} capable of sending messages.
  *
  * @see GuildChannel
  * @see MessageChannel
- * @see VoiceChannel
- * @see Category
+ * @see BaseGuildMessageChannel
  *
  * @see   Guild#getTextChannelCache()
  * @see   Guild#getTextChannels()

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

@@ -29,6 +29,7 @@
 import java.util.Formatter;
 import java.util.List;
 
+//todo-v5: document all
 public interface ThreadChannel extends GuildMessageChannel, IMemberContainer
 {
     //TODO fields that need to be researched: