Skip to content

Commit

Permalink
Javadoc Updates (#1017)
Browse files Browse the repository at this point in the history 
* Update outdated MessageChannel documentation
* Add example to openPrivateChannel
* Update old documentation of JDABuilder#build
* Consistent mentions of (im-)mutability for lists
* Add some examples to RestAction methods
* Add release flag to options to fix error
* Add note about null owner of a guild
  • Loading branch information
@MinnDevelopment
MinnDevelopment authored Jun 16, 2019
1 parent 70a5947 commit 598ba9a
Show file tree
Hide file tree
Showing 30 changed files with 258 additions and 71 deletions.
1 change: 1 addition & 0 deletions build.gradle.kts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -202,6 +202,7 @@ javadoc.apply {
"https://square.github.io/okhttp/3.x/okhttp/")
if (JavaVersion.current().isJava9Compatible) {
opt.addBooleanOption("html5", true)
opt.addStringOption("-release", "8")
}
if (JavaVersion.current().isJava11Compatible) {
opt.addBooleanOption("-no-module-directories", true)
Expand Down
36 changes: 25 additions & 11 deletions src/main/java/net/dv8tion/jda/api/JDA.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -212,6 +212,8 @@ public boolean equals(Object o)
*
* @return {@link net.dv8tion.jda.api.requests.RestAction RestAction} - Type: long
*
* @since 4.0.0
*
* @see #getGatewayPing()
*/
@Nonnull
Expand Down Expand Up @@ -280,6 +282,8 @@ default JDA awaitReady() throws InterruptedException
* executions. This is also used in other parts of JDA related to http requests.
*
* @return The {@link ScheduledExecutorService} used for http request handling
*
* @since 4.0.0
*/
@Nonnull
ScheduledExecutorService getRateLimitPool();
Expand All @@ -289,6 +293,8 @@ default JDA awaitReady() throws InterruptedException
* <br>This involves initial setup of guilds as well as keeping the connection alive.
*
* @return The {@link ScheduledExecutorService} used for WebSocket transmissions
*
* @since 4.0.0
*/
@Nonnull
ScheduledExecutorService getGatewayPool();
Expand All @@ -300,6 +306,8 @@ default JDA awaitReady() throws InterruptedException
* <br>By default this uses the {@link ForkJoinPool#commonPool() CommonPool} of the runtime.
*
* @return The {@link ExecutorService} used for callbacks
*
* @since 4.0.0
*/
@Nonnull
ExecutorService getCallbackPool();
Expand All @@ -308,6 +316,8 @@ default JDA awaitReady() throws InterruptedException
* The {@link OkHttpClient} used for handling http requests from {@link RestAction RestActions}.
*
* @return The http client
*
* @since 4.0.0
*/
@Nonnull
OkHttpClient getHttpClient();
Expand All @@ -320,6 +330,8 @@ default JDA awaitReady() throws InterruptedException
* {@link AudioManager}.
*
* @return The {@link DirectAudioController} for this JDA instance
*
* @since 4.0.0
*/
@Nonnull
DirectAudioController getDirectAudioController();
Expand Down Expand Up @@ -363,7 +375,7 @@ default JDA awaitReady() throws InterruptedException
void removeEventListener(@Nonnull Object... listeners);

/**
* Returns an unmodifiable List of Objects that have been registered as EventListeners.
* Immutable List of Objects that have been registered as EventListeners.
*
* @return List of currently registered Objects acting as EventListeners.
*/
Expand Down Expand Up @@ -432,7 +444,7 @@ default List<AudioManager> getAudioManagers()
SnowflakeCacheView<User> getUserCache();

/**
* An unmodifiable list of all {@link net.dv8tion.jda.api.entities.User Users} that share a
* An immutable list of all {@link net.dv8tion.jda.api.entities.User Users} that share a
* {@link net.dv8tion.jda.api.entities.Guild Guild} with the currently logged in account.
* <br>This list will never contain duplicates and represents all
* {@link net.dv8tion.jda.api.entities.User Users} that JDA can currently see.
Expand All @@ -445,7 +457,7 @@ default List<AudioManager> getAudioManagers()
* a local variable or use {@link #getUserCache()} and use its more efficient
* versions of handling these values.
*
* @return List of all {@link net.dv8tion.jda.api.entities.User Users} that are visible to JDA.
* @return Immutable list of all {@link net.dv8tion.jda.api.entities.User Users} that are visible to JDA.
*/
@Nonnull
default List<User> getUsers()
Expand Down Expand Up @@ -551,7 +563,7 @@ default User getUserByTag(@Nonnull String username, @Nonnull String discriminato
}

/**
* This unmodifiable returns all {@link net.dv8tion.jda.api.entities.User Users} that have the same username as the one provided.
* This immutable returns all {@link net.dv8tion.jda.api.entities.User Users} that have the same username as the one provided.
* <br>If there are no {@link net.dv8tion.jda.api.entities.User Users} with the provided name, then this returns an empty list.
*
* <p><b>Note: </b> This does **not** consider nicknames, it only considers {@link net.dv8tion.jda.api.entities.User#getName()}
Expand All @@ -561,7 +573,7 @@ default User getUserByTag(@Nonnull String username, @Nonnull String discriminato
* @param ignoreCase
* Whether to ignore case or not when comparing the provided name to each {@link net.dv8tion.jda.api.entities.User#getName()}.
*
* @return Possibly-empty list of {@link net.dv8tion.jda.api.entities.User Users} that all have the same name as the provided name.
* @return Possibly-empty immutable list of {@link net.dv8tion.jda.api.entities.User Users} that all have the same name as the provided name.
*/
@Nonnull
default List<User> getUsersByName(@Nonnull String name, boolean ignoreCase)
Expand All @@ -575,7 +587,9 @@ default List<User> getUsersByName(@Nonnull String name, boolean ignoreCase)
* @param users
* The users which all the returned {@link net.dv8tion.jda.api.entities.Guild Guilds} must contain.
*
* @return Unmodifiable list of all {@link net.dv8tion.jda.api.entities.Guild Guild} instances which have all {@link net.dv8tion.jda.api.entities.User Users} in them.
* @return Immutable list of all {@link net.dv8tion.jda.api.entities.Guild Guild} instances which have all {@link net.dv8tion.jda.api.entities.User Users} in them.
*
* @see Guild#isMember(net.dv8tion.jda.api.entities.User)
*/
@Nonnull
List<Guild> getMutualGuilds(@Nonnull User... users);
Expand All @@ -586,7 +600,7 @@ default List<User> getUsersByName(@Nonnull String name, boolean ignoreCase)
* @param users
* The users which all the returned {@link net.dv8tion.jda.api.entities.Guild Guilds} must contain.
*
* @return Unmodifiable list of all {@link net.dv8tion.jda.api.entities.Guild Guild} instances which have all {@link net.dv8tion.jda.api.entities.User Users} in them.
* @return Immutable list of all {@link net.dv8tion.jda.api.entities.Guild Guild} instances which have all {@link net.dv8tion.jda.api.entities.User Users} in them.
*/
@Nonnull
List<Guild> getMutualGuilds(@Nonnull Collection<User> users);
Expand Down Expand Up @@ -659,7 +673,7 @@ default List<User> getUsersByName(@Nonnull String name, boolean ignoreCase)
SnowflakeCacheView<Guild> getGuildCache();

/**
* An unmodifiable List of all {@link net.dv8tion.jda.api.entities.Guild Guilds} that the logged account is connected to.
* An immutable List of all {@link net.dv8tion.jda.api.entities.Guild Guilds} that the logged account is connected to.
* <br>If this account is not connected to any {@link net.dv8tion.jda.api.entities.Guild Guilds}, this will return an empty list.
*
* <p>If the developer is sharding ({@link net.dv8tion.jda.api.JDABuilder#useSharding(int, int)}, then this list
Expand All @@ -673,7 +687,7 @@ default List<User> getUsersByName(@Nonnull String name, boolean ignoreCase)
* a local variable or use {@link #getGuildCache()} and use its more efficient
* versions of handling these values.
*
* @return Possibly-empty list of all the {@link net.dv8tion.jda.api.entities.Guild Guilds} that this account is connected to.
* @return Possibly-empty immutable list of all the {@link net.dv8tion.jda.api.entities.Guild Guilds} that this account is connected to.
*/
@Nonnull
default List<Guild> getGuilds()
Expand Down Expand Up @@ -715,15 +729,15 @@ default Guild getGuildById(long id)
}

/**
* An unmodifiable list of all {@link net.dv8tion.jda.api.entities.Guild Guilds} that have the same name as the one provided.
* An immutable list of all {@link net.dv8tion.jda.api.entities.Guild Guilds} that have the same name as the one provided.
* <br>If there are no {@link net.dv8tion.jda.api.entities.Guild Guilds} with the provided name, then this returns an empty list.
*
* @param name
* The name of the requested {@link net.dv8tion.jda.api.entities.Guild Guilds}.
* @param ignoreCase
* Whether to ignore case or not when comparing the provided name to each {@link net.dv8tion.jda.api.entities.Guild#getName()}.
*
* @return Possibly-empty list of all the {@link net.dv8tion.jda.api.entities.Guild Guilds} that all have the same name as the provided name.
* @return Possibly-empty immutable list of all the {@link net.dv8tion.jda.api.entities.Guild Guilds} that all have the same name as the provided name.
*/
@Nonnull
default List<Guild> getGuildsByName(@Nonnull String name, boolean ignoreCase)
Expand Down
10 changes: 8 additions & 2 deletions src/main/java/net/dv8tion/jda/api/JDABuilder.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,8 @@ public JDABuilder(@Nonnull AccountType accountType)
* True, if JDA should fire {@link net.dv8tion.jda.api.events.RawGatewayEvent}.
*
* @return The JDABuilder instance. Useful for chaining.
*
* @since 4.0.0
*/
@Nonnull
public JDABuilder setRawEventsEnabled(boolean enable)
Expand Down Expand Up @@ -810,6 +812,8 @@ public JDABuilder setSessionController(@Nullable SessionController controller)
*
* @return The JDABuilder instance. Useful for chaining.
*
* @since 4.0.0
*
* @see VoiceDispatchInterceptor
*/
@Nonnull
Expand All @@ -823,8 +827,8 @@ public JDABuilder setVoiceDispatchInterceptor(@Nullable VoiceDispatchInterceptor
* Builds a new {@link net.dv8tion.jda.api.JDA} instance and uses the provided token to start the login process.
* <br>The login process runs in a different thread, so while this will return immediately, {@link net.dv8tion.jda.api.JDA} has not
* finished loading, thus many {@link net.dv8tion.jda.api.JDA} methods have the chance to return incorrect information.
* <br>The main use of this method is to start the JDA connect process and do other things in parallel while startup is
* being performed like database connection or local resource loading.
* For example {@link JDA#getGuilds()} might return an empty list or {@link net.dv8tion.jda.api.JDA#getUserById(long)} might return null
* for arbitrary user IDs.
*
* <p>If you wish to be sure that the {@link net.dv8tion.jda.api.JDA} information is correct, please use
* {@link net.dv8tion.jda.api.JDA#awaitReady() JDA.awaitReady()} or register an
Expand All @@ -838,6 +842,8 @@ public JDABuilder setVoiceDispatchInterceptor(@Nullable VoiceDispatchInterceptor
*
* @return A {@link net.dv8tion.jda.api.JDA} instance that has started the login process. It is unknown as
* to whether or not loading has finished when this returns.
*
* @see net.dv8tion.jda.api.JDA#awaitReady()
*/
@Nonnull
public JDA build() throws LoginException
Expand Down
2 changes: 2 additions & 0 deletions src/main/java/net/dv8tion/jda/api/entities/Category.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,8 @@ public interface Category extends GuildChannel
* listed for this Category
*
* @return Immutable list of all child StoreChannels
*
* @since 4.0.0
*/
@Nonnull
List<StoreChannel> getStoreChannels();
Expand Down
22 changes: 17 additions & 5 deletions src/main/java/net/dv8tion/jda/api/entities/Guild.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -289,10 +289,12 @@ default MemberAction addMember(@Nonnull String accessToken, long userId)

/**
* The {@link net.dv8tion.jda.api.entities.Member Member} object for the owner of this Guild.
* <br>This is null when the owner is no longer in this guild. Sometimes owners of guilds delete their account
* or get banned by Discord.
*
* <p>Ownership can be transferred using {@link net.dv8tion.jda.api.entities.Guild#transferOwnership(Member)}.
*
* @return Member object for the Guild owner.
* @return Possibly-null Member object for the Guild owner.
*
* @see #getOwnerIdLong()
*/
Expand Down Expand Up @@ -841,6 +843,8 @@ default List<Category> getCategoriesByName(@Nonnull String name, boolean ignoreC
* If the provided {@code id} cannot be parsed by {@link Long#parseLong(String)}
*
* @return Possibly-null {@link net.dv8tion.jda.api.entities.StoreChannel StoreChannel} with matching id.
*
* @since 4.0.0
*/
@Nullable
default StoreChannel getStoreChannelById(@Nonnull String id)
Expand All @@ -859,6 +863,8 @@ default StoreChannel getStoreChannelById(@Nonnull String id)
* The id of the {@link net.dv8tion.jda.api.entities.StoreChannel StoreChannel}.
*
* @return Possibly-null {@link net.dv8tion.jda.api.entities.StoreChannel StoreChannel} with matching id.
*
* @since 4.0.0
*/
@Nullable
default StoreChannel getStoreChannelById(long id)
Expand All @@ -876,6 +882,8 @@ default StoreChannel getStoreChannelById(long id)
* versions of handling these values.
*
* @return An immutable List of all {@link net.dv8tion.jda.api.entities.StoreChannel StoreChannel} in this Guild.
*
* @since 4.0.0
*/
@Nonnull
default List<StoreChannel> getStoreChannels()
Expand All @@ -894,6 +902,8 @@ default List<StoreChannel> getStoreChannels()
* Determines if the comparison ignores case when comparing. True - case insensitive.
*
* @return Possibly-empty immutable list of all StoreChannels with names that match the provided name.
*
* @since 4.0.0
*/
@Nonnull
default List<StoreChannel> getStoreChannelsByName(@Nonnull String name, boolean ignoreCase)
Expand All @@ -907,6 +917,8 @@ default List<StoreChannel> getStoreChannelsByName(@Nonnull String name, boolean
* <br>TextChannels are sorted according to their position.
*
* @return {@link net.dv8tion.jda.api.utils.cache.SortedSnowflakeCacheView SortedSnowflakeCacheView}
*
* @since 4.0.0
*/
@Nonnull
SortedSnowflakeCacheView<StoreChannel> getStoreChannelCache();
Expand Down Expand Up @@ -1310,7 +1322,7 @@ default List<Emote> getEmotesByName(@Nonnull String name, boolean ignoreCase)
SnowflakeCacheView<Emote> getEmoteCache();

/**
* Retrieves a list of emotes together with their respective creators.
* Retrieves an immutable list of emotes together with their respective creators.
*
* <p>Note that {@link ListedEmote#getUser()} is only available if the currently
* logged in account has {@link net.dv8tion.jda.api.Permission#MANAGE_EMOTES Permission.MANAGE_EMOTES}.
Expand Down Expand Up @@ -1415,7 +1427,7 @@ default RestAction<ListedEmote> retrieveEmote(@Nonnull Emote emote)
}

/**
* Retrieves an unmodifiable list of the currently banned {@link net.dv8tion.jda.api.entities.User Users}.
* Retrieves an immutable list of the currently banned {@link net.dv8tion.jda.api.entities.User Users}.
* <br>If you wish to ban or unban a user, use either {@link #ban(User, int) ban(User, int)} or
* {@link #unban(User) unban(User)}.
*
Expand All @@ -1433,7 +1445,7 @@ default RestAction<ListedEmote> retrieveEmote(@Nonnull Emote emote)
* If the logged in account does not have the {@link net.dv8tion.jda.api.Permission#BAN_MEMBERS} permission.
*
* @return {@link net.dv8tion.jda.api.requests.RestAction RestAction} - Type: {@literal List<}{@link net.dv8tion.jda.api.entities.Guild.Ban Ban}{@literal >}
* <br>An unmodifiable list of all users currently banned from this Guild
* <br>Retrieves an immutable list of all users currently banned from this Guild
*/
@Nonnull
@CheckReturnValue
Expand Down Expand Up @@ -1761,7 +1773,7 @@ default RestAction<Ban> retrieveBan(@Nonnull User bannedUser)
* {@link net.dv8tion.jda.api.entities.Member Members} in this {@link net.dv8tion.jda.api.entities.Guild Guild}, which is
* impossible.
*
* @return Never-empty list containing all the {@link GuildVoiceState GuildVoiceStates} on this {@link net.dv8tion.jda.api.entities.Guild Guild}.
* @return Never-empty immutable list containing all the {@link GuildVoiceState GuildVoiceStates} on this {@link net.dv8tion.jda.api.entities.Guild Guild}.
*/
@Nonnull
List<GuildVoiceState> getVoiceStates();
Expand Down
16 changes: 10 additions & 6 deletions src/main/java/net/dv8tion/jda/api/entities/GuildChannel.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -73,12 +73,14 @@ public interface GuildChannel extends ISnowflake, Comparable<GuildChannel>

/**
* A List of all {@link net.dv8tion.jda.api.entities.Member Members} that are in this GuildChannel
* For {@link net.dv8tion.jda.api.entities.TextChannel TextChannels},
* <br>For {@link net.dv8tion.jda.api.entities.TextChannel TextChannels},
* this returns all Members with the {@link net.dv8tion.jda.api.Permission#MESSAGE_READ} Permission.
* In {@link net.dv8tion.jda.api.entities.VoiceChannel VoiceChannels},
* <br>For {@link net.dv8tion.jda.api.entities.VoiceChannel VoiceChannels},
* this returns all Members that joined that VoiceChannel.
* <br>For {@link net.dv8tion.jda.api.entities.Category Categories},
* this returns all Members who are in its child channels.
*
* @return A List of {@link net.dv8tion.jda.api.entities.Member Members} that are in this GuildChannel.
* @return An immutable List of {@link net.dv8tion.jda.api.entities.Member Members} that are in this GuildChannel.
*/
@Nonnull
List<Member> getMembers();
Expand Down Expand Up @@ -137,7 +139,7 @@ public interface GuildChannel extends ISnowflake, Comparable<GuildChannel>
* If you would like only {@link net.dv8tion.jda.api.entities.Member Member} overrides or only {@link net.dv8tion.jda.api.entities.Role Role}
* overrides, use {@link #getMemberPermissionOverrides()} or {@link #getRolePermissionOverrides()} respectively.
*
* @return Possibly-empty list of all {@link net.dv8tion.jda.api.entities.PermissionOverride PermissionOverrides}
* @return Possibly-empty immutable list of all {@link net.dv8tion.jda.api.entities.PermissionOverride PermissionOverrides}
* for this {@link GuildChannel GuildChannel}.
*/
@Nonnull
Expand All @@ -147,7 +149,7 @@ public interface GuildChannel extends ISnowflake, Comparable<GuildChannel>
* Gets all of the {@link net.dv8tion.jda.api.entities.Member Member} {@link net.dv8tion.jda.api.entities.PermissionOverride PermissionOverrides}
* that are part of this {@link GuildChannel GuildChannel}.
*
* @return Possibly-empty list of all {@link net.dv8tion.jda.api.entities.PermissionOverride PermissionOverrides}
* @return Possibly-empty immutable list of all {@link net.dv8tion.jda.api.entities.PermissionOverride PermissionOverrides}
* for {@link net.dv8tion.jda.api.entities.Member Member}
* for this {@link GuildChannel GuildChannel}.
*/
Expand All @@ -158,7 +160,7 @@ public interface GuildChannel extends ISnowflake, Comparable<GuildChannel>
* Gets all of the {@link net.dv8tion.jda.api.entities.Role Role} {@link net.dv8tion.jda.api.entities.PermissionOverride PermissionOverrides}
* that are part of this {@link GuildChannel GuildChannel}.
*
* @return Possibly-empty list of all {@link net.dv8tion.jda.api.entities.PermissionOverride PermissionOverrides}
* @return Possibly-empty immutable list of all {@link net.dv8tion.jda.api.entities.PermissionOverride PermissionOverrides}
* for {@link net.dv8tion.jda.api.entities.Role Roles}
* for this {@link GuildChannel GuildChannel}.
*/
Expand Down Expand Up @@ -345,6 +347,8 @@ default ChannelAction<? extends GuildChannel> createCopy()
*
* @return {@link net.dv8tion.jda.api.requests.restaction.PermissionOverrideAction}
* <br>With the current settings of an existing override or a fresh override with no permissions set
*
* @since 4.0.0
*/
@Nonnull
@CheckReturnValue
Expand Down
Loading

0 comments on commit 598ba9a

Please sign in to comment.