Add missing javadocs (#2491)

* Add missing package-info files * Add some more missing package infos * Add overview * Cleanup * Add docs for AudioChannelManager * Add missing channel event docs * Add docs to ContextConsumer * Add docs to GenericEvent * Add exception docs * Add missing manager docs * Add docs to utils * Add docs to ListenerProxy * Add some docs to request classes * Add docs to WebhookType enum * Update examples * Update some docs marked as todo * Fix copy-paste issues
discord-jda · Jul 3, 2023 · e513694 · e513694
1 parent ab3546e
commit e513694
Show file tree

Hide file tree

Showing 132 changed files with 1,317 additions and 169 deletions.
diff --git a/build.gradle.kts b/build.gradle.kts
@@ -282,6 +282,8 @@ javadoc.apply {
         } else {
             opt.addBooleanOption("Xdoclint:all,-missing,-accessibility", true)
         }
+
+        opt.overview = "$projectDir/overview.html"
     }
 
     dependsOn(sourcesJar)

diff --git a/overview.html b/overview.html
@@ -0,0 +1,43 @@
+<!--
+  ~ Copyright 2015 Austin Keener, Michael Ritter, Florian Spieß, and the JDA contributors
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~    http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+
+<body>
+    <p>Welcome to the documentation of the Java Discord API (JDA) library!</p>
+    <p>If you are new to JDA, you can check some of our official guides to get started:
+
+    <ul>
+        <li><a target="_blank" href="https://jda.wiki/setup/intellij/">Setup</a></li>
+        <li><a target="_blank" href="https://jda.wiki/using-jda/getting-started/">Getting Started</a></li>
+        <li><a target="_blank" href="https://jda.wiki/introduction/faq/">Frequently Asked Questions</a></li>
+        <li><a target="_blank" href="https://jda.wiki/using-jda/troubleshooting/">Troubleshooting</a></li>
+        <li><a target="_blank" href="https://jda.wiki/using-jda/using-restaction/">Using RestActions</a></li>
+        <li><a target="_blank" href="https://jda.wiki/using-jda/interactions/">Interactions</a></li>
+    </ul>
+
+    <p>There are also a few examples available to get inspired:
+    <ul>
+        <li><a target="_blank" href="https://github.com/discord-jda/JDA/blob/master/src/examples/java/MessageLoggerExample.java">Message Logging</a></li>
+        <li><a target="_blank" href="https://github.com/discord-jda/JDA/blob/master/src/examples/java/SlashBotExample.java">Slash Commands</a></li>
+        <li><a target="_blank" href="https://github.com/discord-jda/JDA/blob/master/src/examples/java/AudioEchoExample.java">Receiving and Sending Audio</a></li>
+    </ul>
+
+    <p>Other useful resources:
+    <ul>
+        <li><a target="_blank" href="https://github.com/discord-jda/JDA/blob/master/README.md">README</a></li>
+        <li><a target="_blank" href="https://github.com/discord-jda/JDA/releases">Releases and Changelogs</a></li>
+        <li><a target="_blank" href="https://github.com/discord-jda/JDA/issues">Reporting Issues</a></li>
+    </ul>
+</body>
diff --git a/src/examples/java/MessageLoggerExample.java b/src/examples/java/MessageLoggerExample.java
@@ -145,7 +145,7 @@ public void onMessageReceived(@Nonnull MessageReceivedEvent event)
             System.out.printf("[%s] [%#s] %#s: %s\n",
                 event.getGuild().getName(), // The name of the server the user sent the message in, this is generally referred to as "guild" in the API
                 channel, // The %#s makes use of the channel name and displays as something like #general
-                author,  // The %#s makes use of User#getAsTag which results in something like Minn#6688
+                author,  // The %#s makes use of User#getAsTag which results in something like minn or Minn#1337
                 message.getContentDisplay() // This removes any unwanted mention syntax and converts it to a readable string
             );
         }

diff --git a/src/examples/java/SlashBotExample.java b/src/examples/java/SlashBotExample.java
@@ -167,13 +167,13 @@ public void ban(SlashCommandInteractionEvent event, User user, Member member)
 
         // optional ban reason with a lazy evaluated fallback (supplier)
         String reason = event.getOption("reason",
-                () -> "Banned by " + event.getUser().getAsTag(), // used if getOption("reason") is null (not provided)
+                () -> "Banned by " + event.getUser().getName(), // used if getOption("reason") is null (not provided)
                 OptionMapping::getAsString); // used if getOption("reason") is not null (provided)
 
         // Ban the user and send a success response
         event.getGuild().ban(user, delDays, TimeUnit.DAYS)
             .reason(reason) // audit-log ban reason (sets X-AuditLog-Reason header)
-            .flatMap(v -> hook.sendMessage("Banned user " + user.getAsTag())) // chain a followup message after the ban is executed
+            .flatMap(v -> hook.sendMessage("Banned user " + user.getName())) // chain a followup message after the ban is executed
             .queue(); // execute the entire call chain
     }
 

diff --git a/src/main/java/net/dv8tion/jda/api/JDA.java b/src/main/java/net/dv8tion/jda/api/JDA.java
@@ -574,7 +574,7 @@ default boolean awaitShutdown() throws InterruptedException
      * This uses the {@link net.dv8tion.jda.api.hooks.InterfacedEventManager InterfacedEventListener} by default.
      * To switch to the {@link net.dv8tion.jda.api.hooks.AnnotatedEventManager AnnotatedEventManager}, use {@link #setEventManager(IEventManager)}.
      *
-     * Note: when using the {@link net.dv8tion.jda.api.hooks.InterfacedEventManager InterfacedEventListener} (default),
+     * <p>Note: when using the {@link net.dv8tion.jda.api.hooks.InterfacedEventManager InterfacedEventListener} (default),
      * given listener <b>must</b> be instance of {@link net.dv8tion.jda.api.hooks.EventListener EventListener}!
      *
      * @param  listeners

diff --git a/src/main/java/net/dv8tion/jda/api/JDABuilder.java b/src/main/java/net/dv8tion/jda/api/JDABuilder.java
@@ -1187,7 +1187,7 @@ public JDABuilder setEnableShutdownHook(boolean enable)
      * Sets whether or not JDA should try to reconnect if a connection-error is encountered.
      * <br>This will use an incremental reconnect (timeouts are increased each time an attempt fails).
      *
-     * Default: <b>true (enabled)</b>
+     * <p>Default: <b>true (enabled)</b>
      *
      * @param  autoReconnect
      *         If true - enables autoReconnect

diff --git a/src/main/java/net/dv8tion/jda/api/audio/OpusPacket.java b/src/main/java/net/dv8tion/jda/api/audio/OpusPacket.java
@@ -136,7 +136,7 @@ public byte[] getOpusAudio()
      * <br>This method is idempotent and will provide the same result on multiple calls
      * without decoding again.
      *
-     * For most use-cases {@link #getAudioData(double)} should be used instead.
+     * <p>For most use-cases {@link #getAudioData(double)} should be used instead.
      *
      * @throws java.lang.IllegalStateException
      *         If {@link #canDecode()} is false

diff --git a/src/main/java/net/dv8tion/jda/api/audio/hooks/ConnectionListener.java b/src/main/java/net/dv8tion/jda/api/audio/hooks/ConnectionListener.java
@@ -46,6 +46,8 @@ public interface ConnectionListener
      */
     void onStatusChange(@Nonnull ConnectionStatus status);
 
+    // TODO: Deprecate and replace these onUserSpeaking methods.
+
     /**
      * This method is an easy way to detect if a user is talking. Discord sends us an event when a user starts or stops
      * talking and it is parallel to the audio socket, so this event could come milliseconds before or after audio begins

diff --git a/src/main/java/net/dv8tion/jda/api/audio/hooks/ListenerProxy.java b/src/main/java/net/dv8tion/jda/api/audio/hooks/ListenerProxy.java
@@ -24,6 +24,9 @@
 import javax.annotation.Nonnull;
 import java.util.EnumSet;
 
+/**
+ * Internal implementation of {@link ConnectionListener}, to handle possible exceptions thrown by user code.
+ */
 public class ListenerProxy implements ConnectionListener
 {
     private static final Logger log = LoggerFactory.getLogger(ListenerProxy.class);

diff --git a/src/main/java/net/dv8tion/jda/api/entities/Invite.java b/src/main/java/net/dv8tion/jda/api/entities/Invite.java
@@ -696,7 +696,7 @@ enum InviteType
      * A TargetType indicates additional action to be taken by the client on accepting the invite,
      * typically connecting external services or launching external applications depending on the specific TargetType.
      *
-     * Some actions might not be available or show up on certain devices.
+     * <p>Some actions might not be available or show up on certain devices.
      *
      * @see InviteTarget#getType()
      */

diff --git a/src/main/java/net/dv8tion/jda/api/entities/MessageHistory.java b/src/main/java/net/dv8tion/jda/api/entities/MessageHistory.java
@@ -253,7 +253,6 @@ public RestAction<List<Message>> retrievePast(int amount)
      * @throws java.lang.IllegalStateException
      *         If no messages have been retrieved by this MessageHistory.
      *
-     *
      * @return {@link net.dv8tion.jda.api.requests.RestAction RestAction} -
      *         Type: {@link java.util.List List}{@literal <}{@link net.dv8tion.jda.api.entities.Message Message}{@literal >}
      *         <br>Retrieved Messages are placed in a List and provided in order of most recent to oldest with most recent

diff --git a/src/main/java/net/dv8tion/jda/api/entities/MessageType.java b/src/main/java/net/dv8tion/jda/api/entities/MessageType.java
@@ -148,7 +148,7 @@ public enum MessageType
     /**
      * This message was created by the automod system.
      *
-     * Messages from this type usually come with custom embeds containing relevant information, the author is the user that triggered the filter.
+     * <p>Messages from this type usually come with custom embeds containing relevant information, the author is the user that triggered the filter.
      */
     AUTO_MODERATION_ACTION(24, true, true),
 

diff --git a/src/main/java/net/dv8tion/jda/api/entities/WebhookType.java b/src/main/java/net/dv8tion/jda/api/entities/WebhookType.java
@@ -18,6 +18,9 @@
 
 import javax.annotation.Nonnull;
 
+/**
+ * Types of webhooks.
+ */
 public enum WebhookType
 {
     /** Placeholder for unsupported types */

diff --git a/src/main/java/net/dv8tion/jda/api/entities/automod/build/package-info.java b/src/main/java/net/dv8tion/jda/api/entities/automod/build/package-info.java
@@ -0,0 +1,20 @@
+/*
+ * Copyright 2015 Austin Keener, Michael Ritter, Florian Spieß, and the JDA contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Configurations for AutoMod rules and triggers.
+ */
+package net.dv8tion.jda.api.entities.automod.build;
diff --git a/src/main/java/net/dv8tion/jda/api/entities/automod/package-info.java b/src/main/java/net/dv8tion/jda/api/entities/automod/package-info.java
@@ -0,0 +1,20 @@
+/*
+ * Copyright 2015 Austin Keener, Michael Ritter, Florian Spieß, and the JDA contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Types and enums related to AutoMod.
+ */
+package net.dv8tion.jda.api.entities.automod;
diff --git a/src/main/java/net/dv8tion/jda/api/entities/channel/Channel.java b/src/main/java/net/dv8tion/jda/api/entities/channel/Channel.java
@@ -74,7 +74,6 @@ default EnumSet<ChannelFlag> getFlags()
     JDA getJDA();
 
     /**
-     * TODO-v5: Revisit these docs
      * Deletes this Channel.
      *
      * <p>Possible ErrorResponses include:

diff --git a/src/main/java/net/dv8tion/jda/api/entities/channel/attribute/ICategorizableChannel.java b/src/main/java/net/dv8tion/jda/api/entities/channel/attribute/ICategorizableChannel.java
@@ -41,7 +41,7 @@ public interface ICategorizableChannel extends GuildChannel, IPermissionContaine
     /**
      * 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.
+     * <p>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.
      */
@@ -50,7 +50,7 @@ public interface ICategorizableChannel extends GuildChannel, IPermissionContaine
     /**
      * Get the snowflake of the {@link Category Category} that contains this channel.
      *
-     * This will return {@code null} if this channel doesn't have a parent category.
+     * <p>This will return {@code null} if this channel doesn't have a parent category.
      *
      * @return Possibly-null String representation of the Discord ID snowflake of the parent channel.
      */

diff --git a/src/main/java/net/dv8tion/jda/api/entities/channel/attribute/ICopyableChannel.java b/src/main/java/net/dv8tion/jda/api/entities/channel/attribute/ICopyableChannel.java
@@ -27,7 +27,7 @@
 /**
  * Represents a GuildChannel that is capable of being copied.
  *
- * Please see {@link ICopyableChannel#createCopy()} for information on what is copied.
+ * <p>Please see {@link ICopyableChannel#createCopy()} for information on what is copied.
  */
 public interface ICopyableChannel extends GuildChannel
 {

diff --git a/src/main/java/net/dv8tion/jda/api/entities/channel/attribute/IInviteContainer.java b/src/main/java/net/dv8tion/jda/api/entities/channel/attribute/IInviteContainer.java
@@ -29,7 +29,7 @@
 /**
  * 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).
+ * <p>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
 {

diff --git a/src/main/java/net/dv8tion/jda/api/entities/channel/attribute/IMemberContainer.java b/src/main/java/net/dv8tion/jda/api/entities/channel/attribute/IMemberContainer.java
@@ -28,9 +28,9 @@
 /**
  * Represents a {@link GuildChannel} that is capable of containing members.
  *
- * Implementations interpret this meaning as best applies to them:
+ * <p>Implementations interpret this meaning as best applies to them:
  *
- * For example,
+ * <p>For example,
  * <ul>
  *   <li>{@link TextChannel TextChannels} implement this as the {@link net.dv8tion.jda.api.entities.Member members} that have {@link net.dv8tion.jda.api.Permission#VIEW_CHANNEL}</li>
  *   <li>{@link VoiceChannel VoiceChannels} implement this as what {@link net.dv8tion.jda.api.entities.Member members} are currently connected to the channel.</li>

diff --git a/src/main/java/net/dv8tion/jda/api/entities/channel/attribute/IPermissionContainer.java b/src/main/java/net/dv8tion/jda/api/entities/channel/attribute/IPermissionContainer.java
@@ -32,7 +32,7 @@
 /**
  * Represents a {@link GuildChannel} that uses {@link net.dv8tion.jda.api.entities.PermissionOverride Permission Overrides}.
  *
- * Channels that implement this interface can override permissions for specific users or roles.
+ * <p>Channels that implement this interface can override permissions for specific users or roles.
  *
  * @see net.dv8tion.jda.api.entities.PermissionOverride
  */

diff --git a/src/main/java/net/dv8tion/jda/api/entities/channel/attribute/IPositionableChannel.java b/src/main/java/net/dv8tion/jda/api/entities/channel/attribute/IPositionableChannel.java
@@ -24,9 +24,9 @@
 /**
  * Represents a {@link GuildChannel GuildChannel} that has a position.
  *
- * These channels can be re-ordered using a position value.
+ * <p>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.
+ * <p>In the case of identical position values, the natural order of the channel snowflakes is used.
  */
 public interface IPositionableChannel extends GuildChannel
 {

diff --git a/src/main/java/net/dv8tion/jda/api/entities/channel/attribute/IWebhookContainer.java b/src/main/java/net/dv8tion/jda/api/entities/channel/attribute/IWebhookContainer.java
@@ -29,7 +29,7 @@
 /**
  * Represents a {@link GuildChannel} that is capable of utilizing <a href="https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks" target="_blank">webhooks</a>.
  *
- * Webhooks can be used to integrate third-party systems into Discord by way of sending information via messages.
+ * <p>Webhooks can be used to integrate third-party systems into Discord by way of sending information via messages.
  */
 public interface IWebhookContainer extends GuildChannel
 {

diff --git a/src/main/java/net/dv8tion/jda/api/entities/channel/attribute/package-info.java b/src/main/java/net/dv8tion/jda/api/entities/channel/attribute/package-info.java
@@ -0,0 +1,20 @@
+/*
+ * Copyright 2015 Austin Keener, Michael Ritter, Florian Spieß, and the JDA contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Marker interfaces for specific channel features.
+ */
+package net.dv8tion.jda.api.entities.channel.attribute;
diff --git a/src/main/java/net/dv8tion/jda/api/entities/channel/concrete/NewsChannel.java b/src/main/java/net/dv8tion/jda/api/entities/channel/concrete/NewsChannel.java
@@ -34,12 +34,12 @@
 /**
  * Represents {@link net.dv8tion.jda.api.entities.channel.middleman.StandardGuildMessageChannel} that are News Channels.
  *
- * The Discord client may refer to these as Announcement Channels.
+ * <p>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.
+ * <p>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.
+ * <p>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

diff --git a/src/main/java/net/dv8tion/jda/api/entities/channel/concrete/PrivateChannel.java b/src/main/java/net/dv8tion/jda/api/entities/channel/concrete/PrivateChannel.java
@@ -65,12 +65,12 @@ public interface PrivateChannel extends MessageChannel
     /**
      * The human-readable name of this channel.
      *
-     * If getUser returns null, this method will return an empty String.
+     * <p>If getUser returns null, this method will return an empty String.
      * This happens when JDA does not have enough information to populate the channel name.
      *
-     * This will occur only when {@link #getUser()} is null, and the reasons are given in {@link #getUser()}
+     * <p>This will occur only when {@link #getUser()} is null, and the reasons are given in {@link #getUser()}
      *
-     * If the channel name is important, {@link #retrieveUser()} should be used, instead.
+     * <p>If the channel name is important, {@link #retrieveUser()} should be used, instead.
      *
      * @return The name of this channel
      *

diff --git a/src/main/java/net/dv8tion/jda/api/entities/channel/concrete/package-info.java b/src/main/java/net/dv8tion/jda/api/entities/channel/concrete/package-info.java
@@ -0,0 +1,20 @@
+/*
+ * Copyright 2015 Austin Keener, Michael Ritter, Florian Spieß, and the JDA contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Concrete channel types in Discord.
+ */
+package net.dv8tion.jda.api.entities.channel.concrete;
diff --git a/src/main/java/net/dv8tion/jda/api/entities/channel/forums/package-info.java b/src/main/java/net/dv8tion/jda/api/entities/channel/forums/package-info.java
@@ -0,0 +1,20 @@
+/*
+ * Copyright 2015 Austin Keener, Michael Ritter, Florian Spieß, and the JDA contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Types relevant for forum channels and forum posts.
+ */
+package net.dv8tion.jda.api.entities.channel.forums;
diff --git a/src/main/java/net/dv8tion/jda/api/entities/channel/middleman/AudioChannel.java b/src/main/java/net/dv8tion/jda/api/entities/channel/middleman/AudioChannel.java
@@ -48,7 +48,6 @@
  */
 public interface AudioChannel extends StandardGuildChannel
 {
-    //TODO-v5: Docs
     @Override
     @Nonnull
     AudioChannelManager<?, ?> getManager();