Update some outdated and no longer accurate javadoc (#1038)

* Mention exception for removeReaction
* Update description and since tag on setSpeakingDelay
* Change annotation on JDABuilder#setStatus

src/main/java/net/dv8tion/jda/annotations/package-info.java

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2015-2019 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.
+ */
+/**
+ * Annotations used for documentation.
+ */
+package net.dv8tion.jda.annotations;

src/main/java/net/dv8tion/jda/api/EmbedBuilder.java

@@ -120,9 +120,9 @@ public MessageEmbed build()
             throw new IllegalStateException(String.format("Description is longer than %d! Please limit your input!", MessageEmbed.TEXT_MAX_LENGTH));
         if (length() > MessageEmbed.EMBED_MAX_LENGTH_BOT)
             throw new IllegalStateException("Cannot build an embed with more than " + MessageEmbed.EMBED_MAX_LENGTH_BOT + " characters!");
-        final String descrip = this.description.length() < 1 ? null : this.description.toString();
+        final String description = this.description.length() < 1 ? null : this.description.toString();
 
-        return EntityBuilder.createMessageEmbed(url, title, descrip, EmbedType.RICH, timestamp,
+        return EntityBuilder.createMessageEmbed(url, title, description, EmbedType.RICH, timestamp,
                 color, thumbnail, null, author, null, footer, image, new LinkedList<>(fields));
     }
 

src/main/java/net/dv8tion/jda/api/JDABuilder.java

@@ -665,7 +665,8 @@ public JDABuilder setActivity(@Nullable Activity activity)
      * @see    net.dv8tion.jda.api.managers.Presence#setStatus(OnlineStatus) Presence.setStatus(OnlineStatus)
      */
     @Nonnull
-    public JDABuilder setStatus(@Nullable OnlineStatus status)
+    @SuppressWarnings("ConstantConditions") // we have to enforce the nonnull at runtime
+    public JDABuilder setStatus(@Nonnull OnlineStatus status)
     {
         if (status == null || status == OnlineStatus.UNKNOWN)
             throw new IllegalArgumentException("OnlineStatus cannot be null or unknown!");

src/main/java/net/dv8tion/jda/api/audio/SpeakingMode.java

@@ -69,7 +69,7 @@ public static EnumSet<SpeakingMode> getModes(int mask)
     }
 
     /**
-     * Converts the given speaking modes into raw its bitmast.
+     * Converts the given speaking modes into raw its bitmask.
      * This is only useful for sending speaking updates.
      *
      * @param  modes
@@ -88,7 +88,7 @@ public static int getRaw(@Nullable SpeakingMode... modes)
     }
 
     /**
-     * Converts the given speaking modes into raw its bitmast.
+     * Converts the given speaking modes into raw its bitmask.
      * This is only useful for sending speaking updates.
      *
      * @param  modes

src/main/java/net/dv8tion/jda/api/audio/factory/package-info.java

@@ -17,6 +17,6 @@
 /**
  * Audio send factories that can be implemented to generate
  * custom audio send packages to be provided to Discord.
- * <br>A default factory is provided.
+ * <br>A default factory is provided by {@link net.dv8tion.jda.api.audio.factory.DefaultSendFactory DefaultSendFactory}.
  */
 package net.dv8tion.jda.api.audio.factory;

src/main/java/net/dv8tion/jda/api/audio/package-info.java

@@ -16,9 +16,8 @@
 
 /**
  * The audio API for Discord.
- * This is only available if not specifically disabled through the {@link net.dv8tion.jda.api.JDABuilder JDABuilder}.
  *
- * <p>We encode/decode opus audio packages that can be used in an {@link net.dv8tion.jda.internal.audio.AudioConnection AudioConnection}.
+ * <p>We encode/decode opus audio packages that can be used in an audio connection.
  * To interact with the connection an {@link net.dv8tion.jda.api.audio.AudioSendHandler AudioSendHandler}
  * or an {@link net.dv8tion.jda.api.audio.AudioReceiveHandler AudioReceiveHandler} have to be specified the audio manager.
  */

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

@@ -101,7 +101,7 @@ public interface Activity
     static Activity playing(@Nonnull String name)
     {
         Checks.notBlank(name, "Name");
-        return EntityBuilder.createAcitvity(name, null, ActivityType.DEFAULT);
+        return EntityBuilder.createActivity(name, null, ActivityType.DEFAULT);
     }
 
     /**
@@ -130,7 +130,7 @@ static Activity streaming(@Nonnull String name, @Nullable String url)
             type = ActivityType.STREAMING;
         else
             type = ActivityType.DEFAULT;
-        return EntityBuilder.createAcitvity(name, url, type);
+        return EntityBuilder.createActivity(name, url, type);
     }
 
     /**
@@ -149,7 +149,7 @@ static Activity streaming(@Nonnull String name, @Nullable String url)
     static Activity listening(@Nonnull String name)
     {
         Checks.notBlank(name, "Name");
-        return EntityBuilder.createAcitvity(name, null, ActivityType.LISTENING);
+        return EntityBuilder.createActivity(name, null, ActivityType.LISTENING);
     }
 
     /**
@@ -171,7 +171,7 @@ static Activity listening(@Nonnull String name)
     static Activity watching(@Nonnull String name)
     {
         Checks.notBlank(name, "Name");
-        return EntityBuilder.createAcitvity(name, null, ActivityType.WATCHING);
+        return EntityBuilder.createActivity(name, null, ActivityType.WATCHING);
     }
 
     /**

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

@@ -58,7 +58,7 @@ public String getKey()
      * @param  key
      *         The api key to check
      *
-     * @return THe resolved ClientType or {@link #UNKNOWN}
+     * @return The resolved ClientType or {@link #UNKNOWN}
      */
     @Nonnull
     public static ClientType fromKey(@Nonnull String key)

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

@@ -113,7 +113,7 @@ default boolean hasRoles()
 
     /**
      * Whether this emote is managed. A managed Emote is controlled by Discord, not the Guild administrator, typical
-     * via a service like BBTV in conjunction with Twitch.
+     * via a service like BTTV in conjunction with Twitch.
      * <br><a href="https://discordapp.com/developers/docs/resources/emoji#emoji-object" target="_blank">Learn More</a>
      *
      * @return True, if this emote is managed

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

@@ -2828,8 +2828,6 @@ default AuditableRestAction<Void> unban(@Nonnull User user)
      * <br>None of the provided roles may be the <u>Public Role</u> of the current Guild.
      * <br>If a role is both in {@code rolesToAdd} and {@code rolesToRemove} it will be removed.
      *
-     * <p>None of the provided collections may be null
-     *
      * <h1>Warning</h1>
      * <b>This may <u>not</u> be used together with any other role add/remove/modify methods for the same Member
      * within one event listener cycle! The changes made by this require cache updates which are triggered by

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

@@ -863,7 +863,7 @@ default boolean isFromGuild()
      * @throws java.lang.IllegalStateException
      *         <ul>
      *             <li>If the message attempting to be edited was not created by the currently logged in account</li>
-     *             <li>If the message contains a MessageEmebd that is not
+     *             <li>If the message contains a MessageEmbed that is not
      *                 {@link net.dv8tion.jda.api.entities.MessageEmbed#isSendable(net.dv8tion.jda.api.AccountType) sendable}</li>
      *         </ul>
      *

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

@@ -182,14 +182,14 @@ public RestAction<List<Message>> retrievePast(int amount)
         return new RestActionImpl<>(jda, route, (response, request) ->
         {
             EntityBuilder builder = jda.getEntityBuilder();
-            LinkedList<Message> msgs  = new LinkedList<>();
+            LinkedList<Message> messages  = new LinkedList<>();
             DataArray historyJson = response.getArray();
 
             for (int i = 0; i < historyJson.length(); i++)
-                msgs.add(builder.createMessage(historyJson.getObject(i)));
+                messages.add(builder.createMessage(historyJson.getObject(i)));
 
-            msgs.forEach(msg -> history.put(msg.getIdLong(), msg));
-            return msgs;
+            messages.forEach(msg -> history.put(msg.getIdLong(), msg));
+            return messages;
         });
     }
 
@@ -251,19 +251,19 @@ public RestAction<List<Message>> retrieveFuture(int amount)
         return new RestActionImpl<>(jda, route, (response, request) ->
         {
             EntityBuilder builder = jda.getEntityBuilder();
-            LinkedList<Message> msgs  = new LinkedList<>();
+            LinkedList<Message> messages  = new LinkedList<>();
             DataArray historyJson = response.getArray();
 
             for (int i = 0; i < historyJson.length(); i++)
-                msgs.add(builder.createMessage(historyJson.getObject(i)));
+                messages.add(builder.createMessage(historyJson.getObject(i)));
 
-            for (Iterator<Message> it = msgs.descendingIterator(); it.hasNext();)
+            for (Iterator<Message> it = messages.descendingIterator(); it.hasNext();)
             {
                 Message m = it.next();
                 history.put(0, m.getIdLong(), m);
             }
 
-            return msgs;
+            return messages;
         });
     }
 

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

@@ -312,19 +312,22 @@ public RestAction<Void> removeReaction()
      * @throws java.lang.IllegalArgumentException
      *         If the provided {@code user} is null.
      * @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
-     *         if the provided User is not us and we do not have permission to
+     *         If the provided User is not us and we do not have permission to
      *         {@link net.dv8tion.jda.api.Permission#MESSAGE_MANAGE manage messages}
      *         in the channel this reaction was used in
+     * @throws net.dv8tion.jda.api.exceptions.PermissionException
+     *         If the message is from another user in a {@link net.dv8tion.jda.api.entities.PrivateChannel PrivateChannel}
      *
-     * @return {@link net.dv8tion.jda.api.requests.RestAction RestAction} - Type: Void
+     * @return {@link net.dv8tion.jda.api.requests.RestAction RestAction}
      *         Nothing is returned on success
      */
     @Nonnull
     @CheckReturnValue
     public RestAction<Void> removeReaction(@Nonnull User user)
     {
         Checks.notNull(user, "User");
-        if (!user.equals(getJDA().getSelfUser()))
+        boolean self = user.equals(getJDA().getSelfUser());
+        if (!self)
         {
             if (channel.getType() == ChannelType.TEXT)
             {
@@ -341,11 +344,8 @@ public RestAction<Void> removeReaction(@Nonnull User user)
         String code = emote.isEmote()
                     ? emote.getName() + ":" + emote.getId()
                     : EncodingUtil.encodeUTF8(emote.getName());
-        Route.CompiledRoute route;
-        if (user.equals(getJDA().getSelfUser()))
-            route = Route.Messages.REMOVE_REACTION.compile(channel.getId(), getMessageId(), code, "@me");
-        else
-            route = Route.Messages.REMOVE_REACTION.compile(channel.getId(), getMessageId(), code, user.getId());
+        String target = self ? "@me" : user.getId();
+        Route.CompiledRoute route = Route.Messages.REMOVE_REACTION.compile(channel.getId(), getMessageId(), code, target);
         return new RestActionImpl<>(getJDA(), route);
     }
 

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

@@ -112,7 +112,7 @@ public interface TextChannel extends GuildChannel, MessageChannel, IMentionable
      *     <br>The webhook could not be created due to a permission discrepancy</li>
      *
      *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
-     *     <br>The {@link net.dv8tion.jda.api.Permission.VIEW_CHANNEL VIEW_CHANNEL} permission was removed</li>
+     *     <br>The {@link net.dv8tion.jda.api.Permission#VIEW_CHANNEL VIEW_CHANNEL} permission was removed</li>
      * </ul>
      *
      * @param  name

src/main/java/net/dv8tion/jda/api/events/package-info.java

@@ -19,7 +19,7 @@
  * the end-user about the connection state of the current JDA instance.
  *
  * <p>This package contains all implementations of {@link net.dv8tion.jda.api.events.Event Event}.
- * <br>These are specific depending on the event that has been received by the {@link net.dv8tion.jda.internal.requests.WebSocketClient WebSocketClient}
+ * <br>These are specific depending on the event that has been received by the gateway connection.
  *
  * <p>All events are forwarded by an {@link net.dv8tion.jda.api.hooks.IEventManager IEventManager} implementation.
  * <br>Some events are specific for JDA internal events such as the {@link net.dv8tion.jda.api.events.ReadyEvent ReadyEvent}

src/main/java/net/dv8tion/jda/api/hooks/package-info.java

@@ -28,6 +28,6 @@
  * <p>The {@link net.dv8tion.jda.api.hooks.AnnotatedEventManager AnnotatedEventManager}
  * can forward events directly to methods that have the {@link net.dv8tion.jda.api.hooks.SubscribeEvent SubscribeEvent} annotation.
  *
- * <p><b>Note: All of the standard EventManager implementations are synchronized</b>
+ * <p><b>Note: All of the standard EventManager implementations are single-threaded</b>
  */
 package net.dv8tion.jda.api.hooks;

src/main/java/net/dv8tion/jda/api/managers/AudioManager.java

@@ -149,7 +149,7 @@ default void setSpeakingMode(@Nonnull SpeakingMode... mode)
      * <br>This can be useful for send systems that buffer a certain interval of audio frames that will be sent.
      * By default the delay is 200 milliseconds which is also the minimum delay.
      *
-     * <p>If the delay is less than 200 milliseconds it will reset it the minimum delay. The provided delay
+     * <p>If the delay is less than 200 milliseconds it will use the minimum delay. The provided delay
      * will be aligned to the audio frame length of 20 milliseconds by means of integer division. This means
      * it will be rounded down to the next biggest multiple of 20.
      *
@@ -158,6 +158,8 @@ default void setSpeakingMode(@Nonnull SpeakingMode... mode)
      *
      * @param millis
      *        The delay that should be used, in milliseconds
+     *
+     * @since 4.0.0
      */
     void setSpeakingDelay(int millis);
 

src/main/java/net/dv8tion/jda/api/managers/package-info.java

@@ -19,8 +19,8 @@
  * with either an update task or atomic setters. This also includes classes which allow to
  * operate on entities like the moderation of a {@link net.dv8tion.jda.api.entities.Guild Guild}.
  *
- * <p>Manager types allow to directly modify one or more values
+ * <p>Manager types allow to directly modify one or more values.
  *
- * <p>All managers require a RestAction execution.
+ * <p>Almost all managers require a RestAction execution.
  */
 package net.dv8tion.jda.api.managers;

src/main/java/net/dv8tion/jda/api/package-info.java

@@ -15,14 +15,11 @@
  */
 
 /**
- * The api JDA features that are both available for
- * BOT and CLIENT applications.
+ * The API features of JDA.
  *
  * <p>This package contains information about the JDA version used by this library.
  * See {@link net.dv8tion.jda.api.JDAInfo JDAInfo}!
  *
- * <p>It includes enums that can be found at various locations throughout {@link net.dv8tion.jda} not only the api package!
- *
  * <p>To build a JDA instance you
  * would use the {@link net.dv8tion.jda.api.JDABuilder JDABuilder} with a specified {@link net.dv8tion.jda.api.AccountType AccountType}
  * to differ between a bot and a client account. Client accounts are commonly referenced as User accounts due to them being used by

src/main/java/net/dv8tion/jda/api/requests/package-info.java

@@ -15,27 +15,13 @@
  */
 
 /**
- * Discord API connection internals.
- * Includes REST and WebSocket connections
+ * Discord API communication features.
  *
- * <p><u><b>REST API</b></u>
- * <br>The {@link net.dv8tion.jda.internal.requests.Requester Requester}
- * is used to create HTTPs requests with the Discord API through {@link net.dv8tion.jda.internal.requests.Route Routes}.
- * <br>This automatically handles rate limitations (429) that restrict our request rates. For that it uses an implementation
- * of {@link net.dv8tion.jda.internal.requests.RateLimiter RateLimiter} specific for a certain {@link net.dv8tion.jda.api.AccountType AccountType}.
- * <br>{@link net.dv8tion.jda.api.requests.restaction Learn More}
- *
- * <p>The {@link net.dv8tion.jda.api.requests.RestAction RestAction} can be found throughout JDA and allows
+ * <p>The {@link net.dv8tion.jda.api.requests.RestAction RestAction} interface can be found throughout JDA and allows
  * to specify how the Requester should deal with rate limits.
  * It has extensions with additional functionalities in {@link net.dv8tion.jda.api.requests.restaction}.
  *
  * <p>In the case of a failed Request the RestAction will be provided with an {@link net.dv8tion.jda.api.exceptions.ErrorResponseException ErrorResponseException}
  * which contains a {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponse} representing the failure cause!
- *
- * <p><u><b>WebSocket API</b></u>
- * <br>The {@link net.dv8tion.jda.internal.requests.WebSocketClient WebSocketClient} is used to
- * handle the {@link net.dv8tion.jda.api.events.Event Event} flow and connection to the Discord gateway.
- * <br>It can send {@link net.dv8tion.jda.api.managers.Presence Presence} updates that will determine how
- * the Discord Client will display the currently connected account (Online Status / Activity)
  */
 package net.dv8tion.jda.api.requests;

src/main/java/net/dv8tion/jda/api/requests/restaction/order/package-info.java

@@ -24,7 +24,7 @@
  *     <li>{@link net.dv8tion.jda.api.requests.restaction.order.RoleOrderAction Roles}</li>
  * </ul>
  *
- * <p>Abstract base implementation can be found at {@link net.dv8tion.jda.api.requests.restaction.order.OrderAction OrderAction}
+ * <p>The abstract base can be found at {@link net.dv8tion.jda.api.requests.restaction.order.OrderAction OrderAction}.
  *
  * @since 3.0
  */

src/main/java/net/dv8tion/jda/api/requests/restaction/pagination/package-info.java

@@ -16,10 +16,10 @@
 
 /**
  * Extensions of {@link net.dv8tion.jda.api.requests.RestAction RestAction} that allow
- * to access paginated discord endpoints like {@link net.dv8tion.jda.internal.requests.Route.Messages#GET_REACTION_USERS Route.Messages.GET_REACTION_USERS}
+ * to access paginated discord endpoints like the message history of a {@link net.dv8tion.jda.api.entities.MessageChannel MessageChannel}.
  * <br>The {@link net.dv8tion.jda.api.requests.restaction.pagination.PaginationAction PaginationAction} is designed to work
  * as an {@link java.lang.Iterable Iterable} of the specified endpoint. Each implementation specifies the endpoints it will
- * use in the class-level javadoc
+ * use in the class-level javadoc.
  *
  * @since 3.1
  */

src/main/java/net/dv8tion/jda/api/sharding/package-info.java

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2015-2019 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.
+ */
+/**
+ * Implementations for {@link net.dv8tion.jda.api.sharding.ShardManager ShardManager} which enable
+ * auto-sharding.
+ */
+package net.dv8tion.jda.api.sharding;

src/main/java/net/dv8tion/jda/api/utils/WidgetUtil.java

@@ -309,7 +309,7 @@ private Widget(long guildId)
          * Constructs an available Widget
          *
          * @param json
-         *        The {@link org.json.JSONObject JSONObject} to construct the Widget from
+         *        The {@link net.dv8tion.jda.api.utils.data.DataObject DataObject} to construct the Widget from
          */
         private Widget(@Nonnull DataObject json)
         {
@@ -563,7 +563,7 @@ private Member(@Nonnull DataObject json, @Nonnull Widget widget)
                 this.avatar = json.getString("avatar", null);
                 this.nickname = json.getString("nick", null);
                 this.status = OnlineStatus.fromKey(json.getString("status"));
-                this.game = json.isNull("game") ? null : EntityBuilder.createAcitvity(json.getObject("game"));
+                this.game = json.isNull("game") ? null : EntityBuilder.createActivity(json.getObject("game"));
             }
 
             private void setVoiceState(VoiceState voiceState)