Some documentation on //todo-v5: docs (#1838)

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,16 @@
 import javax.annotation.Nullable;
 import java.util.List;
 
-//TODO-v5: Docs
+
+/**
+ * Represents a standard {@link Guild Guild} {@link MessageChannel MessageChannel}.
+ * <br>These are the "<i>normal</i>" message channels that are present in the channel sidebar.
+ * These are <b>not</b> {@link ThreadChannel ThreadChannels}.
+ *
+ * @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,186 @@
 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}.
+ * <br>
+ * Values of this enum without an {@link AuditLogKey} are not tracked by the Audit Log.
+ *
+ * @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 ICategorizableChannel Categorizable Channels} (and implementations).
+     *
+     * @see ICategorizableChannel#getParentCategory()
+     */
+    PARENT("parent", AuditLogKey.CHANNEL_PARENT),
+
+    //TODO-v5 if the calculation of IPositionableChannel#getPosition() changes, this may need modification too.
+    /**
+     * The position of this channel relative to other channels in the guild.
+     *
+     * @see IPositionableChannel#getPosition()
+     *
+     */
     POSITION("position", null), //Discord doesn't track Channel position changes in AuditLog.
 
+
+    //Text Specific
+
+    /**
+     * The topic of the channel.
+     *
+     * Limited to {@link NewsChannel NewsChannels} and {@link TextChannel TextChannels}.
+     *
+     * @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.
+     * <br>
+     * The bitrates of boost tiers may be found in {@link Guild.BoostTier the boost tiers}.
+     *
+     * 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()
+     * @see net.dv8tion.jda.api.entities.ThreadChannel.AutoArchiveDuration
+     */
     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 time this channel's archival information was last updated.
+     *
+     * This timestamp will be updated when any of the following happen:
+     * <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()
+     */
     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 {@link ThreadChannel}.
+ *
+ * @see BaseGuildMessageChannel
+ *
+ */
 public interface GuildMessageChannel extends GuildChannel, MessageChannel
 {
     @Override

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

@@ -21,15 +21,28 @@
 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.
+     *
+     * This will return {@code 0} if this channel doesn't have a parent category.
+     *
+     * @return The Discord ID snowflake of the parent channel as a long.
+     */
     long 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,20 @@
 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:
+ *
+ * For example,
+ * <ul>
+ *   <li>{@link TextChannel TextChannels} implement this as the {@link Member members} that have {@link net.dv8tion.jda.api.Permission#VIEW_CHANNEL}</li>
+ *   <li>{@link VoiceChannel VoiceChannels} implement this as what {@link Member members} are currently connected to the channel.</li>
+ * </ul>
+ *
+ *
+ * @see IMemberContainer#getMembers()
+ */
 public interface IMemberContainer extends GuildChannel
 {
     /**

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

@@ -27,7 +27,13 @@
 import java.util.List;
 import java.util.stream.Collectors;
 
-//TODO-v5: Need Docs
+/**
+ * Represents a {@link GuildChannel} that uses {@link PermissionOverride Permission Overrides}.
+ *
+ * Channels that implement this interface can override permissions for specific users or roles.
+ *
+ * @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 position values, the natural order of the channel snowflakes is used.
+ */
 public interface IPositionableChannel extends GuildChannel
 {
     //TODO-v5: Docs