Skip to content

Commit

Permalink
Improve docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@freya022
freya022 committed Oct 18, 2024
1 parent 62375ff commit a717169
Show file tree
Hide file tree
Showing 5 changed files with 64 additions and 15 deletions.
2 changes: 1 addition & 1 deletion src/main/java/net/dv8tion/jda/api/JDA.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1786,7 +1786,7 @@ default List<RichCustomEmoji> getEmojisByName(@Nonnull String name, boolean igno
RestAction<@Unmodifiable List<StickerPack>> retrieveNitroStickerPacks();

/**
* Retrieves a list of the default {@link SoundboardSound soundboard sounds}.
* Retrieves a list of the default {@link SoundboardSound SoundboardSounds}.
*
* @return {@link RestAction} - Type: List of {@link SoundboardSound}
*/
Expand Down
16 changes: 11 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 @@ -2102,10 +2102,10 @@ default SoundboardSound getSoundboardSoundById(long id)
*
* <p>This copies the backing store into a list. This means every call
* creates a new list with O(n) complexity. It is recommended to store this into
* a local variable or use {@link #getStickerCache()} and use its more efficient
* a local variable or use {@link #getSoundboardSoundCache()} and use its more efficient
* versions of handling these values.
*
* <p>This requires the {@link CacheFlag#STICKER} to be enabled!
* <p>This requires the {@link CacheFlag#SOUNDBOARD_SOUNDS} to be enabled!
*
* @return An immutable List of {@link SoundboardSound SoundboardSounds}.
*/
Expand All @@ -2128,7 +2128,7 @@ default List<SoundboardSound> getSoundboardSounds()
* @param ignoreCase
* Determines if the comparison ignores case when comparing. True - case insensitive.
*
* @return Possibly-empty immutable list of all Soundboard sounds that match the provided name.
* @return Possibly-empty immutable list of all SoundboardSounds that match the provided name.
*/
@Nonnull
@Unmodifiable
Expand Down Expand Up @@ -5112,7 +5112,7 @@ default AuditableRestAction<GuildSticker> createSticker(@Nonnull String name, @N
/**
* Creates a soundboard sound in the guild.
*
* <p>The returned {@link RestAction} can encounter the following Discord errors:
* <p>The returned {@link RestAction} can encounter the following {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses}:
* <ul>
* <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#INVALID_FILE_EXCEEDS_MAXIMUM_LENGTH INVALID_FILE_EXCEEDS_MAXIMUM_LENGTH}
* <br>The provided file exceeds the duration of 5.2 seconds</li>
Expand All @@ -5126,11 +5126,17 @@ default AuditableRestAction<GuildSticker> createSticker(@Nonnull String name, @N
* <br>The file is malformed</li>
* </ul>
*
* @param name
* The name of the soundboard sound, must be between 2-32 characters
* @param file
* The file to use as the sound, can be an MP3 or an OGG file
*
* @throws IllegalArgumentException
* If {@code null} is provided, or {@code name} is not between 2-32 characters
* <ul>
* <li>If {@code null} is provided</li>
* <li>If {@code name} is not between 2-32 characters</li>
* <li>If the file is not of the correct type</li>
* </ul>
* @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
* If the currently logged in account does not have {@link Permission#CREATE_GUILD_EXPRESSIONS CREATE_GUILD_EXPRESSIONS} in the guild.
*
Expand Down
55 changes: 49 additions & 6 deletions src/main/java/net/dv8tion/jda/api/entities/SoundboardSound.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ default String getUrl()
/**
* The user which created this sound.
*
* <p>This is present only if the {@link Guild#getSelfMember() current member} has
* <p>This is present only if the {@link Guild#getSelfMember() self member} has
* the {@link Permission#CREATE_GUILD_EXPRESSIONS CREATE_GUILD_EXPRESSIONS}
* or {@link Permission#MANAGE_GUILD_EXPRESSIONS MANAGE_GUILD_EXPRESSIONS} permission.
*
Expand All @@ -116,27 +116,31 @@ default String getUrl()
* <br>You must be connected to the voice channel to use this method,
* as well as be able to speak and hear.
*
* <p>Possible {@link ErrorResponse ErrorResponses} caused by
* the returned {@link RestAction} include the following:
* <p>The returned {@link RestAction} can encounter the following {@link ErrorResponse ErrorResponses}:
* <ul>
* <li>{@link ErrorResponse#MISSING_PERMISSIONS MISSING_PERMISSIONS}
* <br>The sound cannot be sent due to a permission discrepancy</li>
* <li>{@link ErrorResponse#CANNOT_SEND_VOICE_EFFECT CANNOT_SEND_VOICE_EFFECT}
* <br>The sound cannot be sent as the bot is either muted, deafened or suppressed</li>
* <li>{@link ErrorResponse#UNKNOWN_SOUND UNKNOWN_SOUND}
* <br>The sound was deleted</li>
* </ul>
*
* @param channel
* The channel to send this sound on
*
* @throws InsufficientPermissionException
* If the logged in account does not have the {@link Permission#VOICE_SPEAK VOICE_SPEAK},
* {@link Permission#VOICE_USE_SOUNDBOARD VOICE_USE_SOUNDBOARD},
* or {@link Permission#VOICE_USE_EXTERNAL_SOUNDS VOICE_USE_EXTERNAL_SOUNDS} permission.
* If the bot does not have the following permissions:
* <ul>
* <li>{@link Permission#VOICE_SPEAK VOICE_SPEAK}, {@link Permission#VOICE_USE_SOUNDBOARD VOICE_USE_SOUNDBOARD}</li>
* <li>When used in other guilds, {@link Permission#VOICE_USE_EXTERNAL_SOUNDS VOICE_USE_EXTERNAL_SOUNDS} permission</li>
* </ul>
* @throws IllegalArgumentException
* If the provided channel is {@code null}
* @throws IllegalStateException
* <ul>
* <li>If {@link GatewayIntent#GUILD_VOICE_STATES} is not enabled</li>
* <li>If the sound is not {@link #isAvailable() available}</li>
* <li>If the bot is not connected to the specified channel</li>
* <li>If the bot is deafened, muted or suppressed in the target guild</li>
* </ul>
Expand All @@ -147,10 +151,49 @@ default String getUrl()
@CheckReturnValue
RestAction<Void> sendTo(VoiceChannel channel);

/**
* Deletes this soundboard sound.
*
* <p>The returned {@link RestAction} can encounter the following {@link ErrorResponse ErrorResponses}:
* <ul>
* <li>{@link ErrorResponse#MISSING_PERMISSIONS MISSING_PERMISSIONS}
* <br>The sound cannot be deleted due to a permission discrepancy</li>
* <li>{@link ErrorResponse#UNKNOWN_SOUND UNKNOWN_SOUND}
* <br>The sound was deleted</li>
* </ul>
*
* @throws InsufficientPermissionException
* <ul>
* <li>If the bot does not own this sound and does not have {@link Permission#MANAGE_GUILD_EXPRESSIONS}</li>
* <li>If the bot owns this sound and does not have {@link Permission#MANAGE_GUILD_EXPRESSIONS} or {@link Permission#CREATE_GUILD_EXPRESSIONS}</li>
* </ul>
*
* @return {@link RestAction} - Type: {@link Void}
*/
@Nonnull
@CheckReturnValue
RestAction<Void> delete();

/**
* The {@link SoundboardSoundManager} for this soundboard sound, in which you can modify values.
* <br>You modify multiple fields in one request by chaining setters before calling {@link RestAction#queue()}.
*
* <p>The returned {@link RestAction} can encounter the following {@link ErrorResponse ErrorResponses}:
* <ul>
* <li>{@link ErrorResponse#MISSING_PERMISSIONS MISSING_PERMISSIONS}
* <br>The sound cannot be edited due to a permission discrepancy</li>
* <li>{@link ErrorResponse#UNKNOWN_SOUND UNKNOWN_SOUND}
* <br>The sound was deleted</li>
* </ul>
*
* @throws InsufficientPermissionException
* <ul>
* <li>If the bot does not own this sound and does not have {@link Permission#MANAGE_GUILD_EXPRESSIONS}</li>
* <li>If the bot owns this sound and does not have {@link Permission#MANAGE_GUILD_EXPRESSIONS} or {@link Permission#CREATE_GUILD_EXPRESSIONS}</li>
* </ul>
*
* @return The SoundboardSoundManager of this soundboard sound
*/
@Nonnull
@CheckReturnValue
SoundboardSoundManager getManager();
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/net/dv8tion/jda/api/events/soundboard/update/package-info.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
*/

/**
* Events that track updates for existing {@link net.dv8tion.jda.api.entities.SoundboardSound Soundboard sounds}
* Events that track updates for existing {@link net.dv8tion.jda.api.entities.SoundboardSound SoundboardSounds}
*
* <p><b>Requirements</b><br>
*
Expand Down
4 changes: 2 additions & 2 deletions src/main/java/net/dv8tion/jda/api/managers/SoundboardSoundManager.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@
* .setEmoji(null)
* .queue();
* manager.reset(SoundboardSoundManager.VOLUME | SoundboardSoundManager.EMOJI)
* .setVolume("1")
* .setEmoji(Color.RED)
* .setVolume(1)
* .setEmoji(Emoji.fromUnicode("🤔"))
* .queue();
* }</pre>
*
Expand Down

0 comments on commit a717169

Please sign in to comment.