From 3c75c2399da5fa0c2a0f209d63e71765e16eec96 Mon Sep 17 00:00:00 2001 From: NoComment1105 Date: Mon, 21 Nov 2022 00:14:30 +0000 Subject: [PATCH 01/17] Lets get this show on the road --- .../event/channel/ChannelPinsUpdateEvent.kt | 40 +++++++++++++++++++ .../kotlin/event/channel/TypingStartEvent.kt | 34 +++++++++++++++- 2 files changed, 73 insertions(+), 1 deletion(-) diff --git a/core/src/main/kotlin/event/channel/ChannelPinsUpdateEvent.kt b/core/src/main/kotlin/event/channel/ChannelPinsUpdateEvent.kt index 1bdd798e721a..41cd3e2a0d0d 100644 --- a/core/src/main/kotlin/event/channel/ChannelPinsUpdateEvent.kt +++ b/core/src/main/kotlin/event/channel/ChannelPinsUpdateEvent.kt @@ -1,6 +1,7 @@ package dev.kord.core.event.channel import dev.kord.common.entity.Snowflake +import dev.kord.common.exception.RequestException import dev.kord.core.Kord import dev.kord.core.behavior.GuildBehavior import dev.kord.core.behavior.channel.MessageChannelBehavior @@ -8,12 +9,22 @@ import dev.kord.core.entity.Strategizable import dev.kord.core.entity.channel.MessageChannel import dev.kord.core.event.Event import dev.kord.core.event.channel.data.ChannelPinsUpdateEventData +import dev.kord.core.exception.EntityNotFoundException import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy import dev.kord.core.supplier.getChannelOf import dev.kord.core.supplier.getChannelOfOrNull import kotlinx.datetime.Instant +/** + * The event of a channels Pins being updated. + * + * @property data The data associated with the event + * @property kord The Kord Instance + * @property shard The shard for the event + * @property customContext Any custom context provided + * @property supplier The entity supplier to use for the event + */ public class ChannelPinsUpdateEvent( public val data: ChannelPinsUpdateEventData, override val kord: Kord, @@ -22,20 +33,49 @@ public class ChannelPinsUpdateEvent( override val supplier: EntitySupplier = kord.defaultSupplier, ) : Event, Strategizable { + /** + * The ID of the channel that triggered the event + */ public val channelId: Snowflake get() = data.channelId + /** + * The ID of the guild that triggered the event, or null + */ public val guildId: Snowflake? get() = data.guildId.value + /** + * The timestamp of the last pin, or null. + */ public val lastPinTimestamp: Instant? get() = data.lastPinTimestamp.value + /** + * The [Guild][GuildBehavior] that triggered the event, or null. + */ public val guild: GuildBehavior? get() = guildId?.let { GuildBehavior(it, kord) } + /** + * The channel that triggered the event. + */ public val channel: MessageChannelBehavior get() = MessageChannelBehavior(channelId, kord) + /** + * Requests to get the channel for the event as type [MessageChannel] + * + * @throws RequestException if something went wrong while retrieving the channel. + * @throws EntityNotFoundException if the channel is null. + */ public suspend fun getChannel(): MessageChannel = supplier.getChannelOf(channelId) + /** + * Requests to get the channel for the event as type [MessageChannel] or null + * + * @throws RequestException if something went wrong while retrieving the channel. + */ public suspend fun getChannelOrNull(): MessageChannel? = supplier.getChannelOfOrNull(channelId) + /** + * Returns a copy of this class with a new [supplier] provided by the [strategy]. + */ override fun withStrategy(strategy: EntitySupplyStrategy<*>): ChannelPinsUpdateEvent = ChannelPinsUpdateEvent(data, kord, shard, customContext, strategy.supply(kord)) diff --git a/core/src/main/kotlin/event/channel/TypingStartEvent.kt b/core/src/main/kotlin/event/channel/TypingStartEvent.kt index 0adcabdd2bf2..f738c270cd29 100644 --- a/core/src/main/kotlin/event/channel/TypingStartEvent.kt +++ b/core/src/main/kotlin/event/channel/TypingStartEvent.kt @@ -19,6 +19,15 @@ import dev.kord.core.supplier.getChannelOf import dev.kord.core.supplier.getChannelOfOrNull import kotlinx.datetime.Instant +/** + * The event that typing begins in a channel. + * + * @property data The data associated with the event + * @property kord The Kord Instance + * @property shard The shard for the event + * @property customContext Any custom context provided + * @property supplier The entity supplier to use for the event + */ public class TypingStartEvent( public val data: TypingStartEventData, override val kord: Kord, @@ -26,19 +35,39 @@ public class TypingStartEvent( override val customContext: Any?, override val supplier: EntitySupplier = kord.defaultSupplier, ) : Event, Strategizable { - + /** + * The ID of the channel that triggered the event. + */ public val channelId: Snowflake get() = data.channelId + /** + * The ID of the user that triggered the event. + */ public val userId: Snowflake get() = data.userId + /** + * The ID of the guild that triggered the event. + */ public val guildId: Snowflake? get() = data.guildId.value + /** + * The [Instant] this event was triggered. + */ public val started: Instant get() = data.timestamp + /** + * The channel that triggered the event. + */ public val channel: MessageChannelBehavior get() = MessageChannelBehavior(channelId, kord) + /** + * The [Guild][GuildBehavior] that triggered the event. + */ public val guild: GuildBehavior? get() = guildId?.let { GuildBehavior(it, kord) } + /** + * The [User][UserBehavior] that triggered the event. + */ public val user: UserBehavior get() = UserBehavior(userId, kord) /** @@ -81,6 +110,9 @@ public class TypingStartEvent( */ public suspend fun getGuild(): Guild? = guildId?.let { supplier.getGuildOrNull(it) } + /** + * Returns a copy of this class with a new [supplier] provided by the [strategy]. + */ override fun withStrategy(strategy: EntitySupplyStrategy<*>): TypingStartEvent = TypingStartEvent(data, kord, shard, customContext, strategy.supply(kord)) From d73ff4ca529abb362a2b4b34010af55a09ca2838 Mon Sep 17 00:00:00 2001 From: NoComment1105 Date: Mon, 21 Nov 2022 17:58:01 +0000 Subject: [PATCH 02/17] More doc progress --- .../event/channel/ChannelCreateEvent.kt | 41 +++++++++++- .../event/channel/ChannelDeleteEvent.kt | 40 ++++++++++++ .../event/channel/ChannelPinsUpdateEvent.kt | 2 + .../event/channel/ChannelUpdateEvent.kt | 62 ++++++++++++++++++- .../kotlin/event/channel/TypingStartEvent.kt | 3 + .../event/channel/thread/ThreadCreateEvent.kt | 22 ++++++- .../event/channel/thread/ThreadDeleteEvent.kt | 23 ++++++- .../channel/thread/ThreadListSyncEvent.kt | 29 ++++++++- .../event/channel/thread/ThreadUpdateEvent.kt | 23 ++++++- 9 files changed, 232 insertions(+), 13 deletions(-) diff --git a/core/src/main/kotlin/event/channel/ChannelCreateEvent.kt b/core/src/main/kotlin/event/channel/ChannelCreateEvent.kt index dcb7461a16b8..a539f7a81315 100644 --- a/core/src/main/kotlin/event/channel/ChannelCreateEvent.kt +++ b/core/src/main/kotlin/event/channel/ChannelCreateEvent.kt @@ -4,12 +4,22 @@ import dev.kord.core.Kord import dev.kord.core.entity.channel.* import dev.kord.core.event.Event +/** + * The event dispatched when a [Channel] is created in a guild. + * + * @see Channel Create + */ public interface ChannelCreateEvent : Event { public val channel: Channel override val kord: Kord get() = channel.kord } +/** + * The event dispatched when a [Category] is created in a guild. + * + * @see Channel Create + */ public class CategoryCreateEvent( override val channel: Category, override val shard: Int, @@ -20,6 +30,11 @@ public class CategoryCreateEvent( } } +/** + * The event dispatched when a [DmChannel] is created in a guild. + * + * @see Channel Create + */ public class DMChannelCreateEvent( override val channel: DmChannel, override val shard: Int, @@ -30,6 +45,11 @@ public class DMChannelCreateEvent( } } +/** + * The event dispatched when a [NewsChannel] is created in a guild. + * + * @see Channel Create + */ public class NewsChannelCreateEvent( override val channel: NewsChannel, override val shard: Int, @@ -40,6 +60,11 @@ public class NewsChannelCreateEvent( } } +/** + * The event dispatched when a [TextChannel] is created in a guild. + * + * @see Channel Create + */ public class TextChannelCreateEvent( override val channel: TextChannel, override val shard: Int, @@ -50,6 +75,11 @@ public class TextChannelCreateEvent( } } +/** + * The event dispatched when a [VoiceChannel] is created in a guild. + * + * @see Channel Create + */ public class VoiceChannelCreateEvent( override val channel: VoiceChannel, override val shard: Int, @@ -60,7 +90,11 @@ public class VoiceChannelCreateEvent( } } - +/** + * The event dispatched when a [StageChannel] is created in a guild. + * + * @see Channel Create + */ public class StageChannelCreateEvent( override val channel: StageChannel, override val shard: Int, @@ -71,6 +105,11 @@ public class StageChannelCreateEvent( } } +/** + * The event dispatched when an Unknown [Channel] is created in a guild. + * + * @see Channel Create + */ public class UnknownChannelCreateEvent( override val channel: Channel, override val shard: Int, diff --git a/core/src/main/kotlin/event/channel/ChannelDeleteEvent.kt b/core/src/main/kotlin/event/channel/ChannelDeleteEvent.kt index 479331ec2136..abf0dcedffdf 100644 --- a/core/src/main/kotlin/event/channel/ChannelDeleteEvent.kt +++ b/core/src/main/kotlin/event/channel/ChannelDeleteEvent.kt @@ -4,12 +4,22 @@ import dev.kord.core.Kord import dev.kord.core.entity.channel.* import dev.kord.core.event.Event +/** + * The event dispatched when a [Channel] is deleted in a guild. + * + * @see Channel Delete + */ public interface ChannelDeleteEvent : Event { public val channel: Channel override val kord: Kord get() = channel.kord } +/** + * The event dispatched when a [Category] is deleted in a guild. + * + * @see Channel Delete + */ public class CategoryDeleteEvent( override val channel: Category, override val shard: Int, @@ -20,6 +30,11 @@ public class CategoryDeleteEvent( } } +/** + * The event dispatched when a [DmChannel] is deleted in a guild. + * + * @see Channel Delete + */ public class DMChannelDeleteEvent( override val channel: DmChannel, override val shard: Int, @@ -30,6 +45,11 @@ public class DMChannelDeleteEvent( } } +/** + * The event dispatched when a [NewsChannel] is deleted in a guild. + * + * @see Channel Delete + */ public class NewsChannelDeleteEvent( override val channel: NewsChannel, override val shard: Int, @@ -40,6 +60,11 @@ public class NewsChannelDeleteEvent( } } +/** + * The event dispatched when a [TextChannel] is deleted in a guild. + * + * @see Channel Delete + */ public class TextChannelDeleteEvent( override val channel: TextChannel, override val shard: Int, @@ -50,6 +75,11 @@ public class TextChannelDeleteEvent( } } +/** + * The event dispatched when a [VoiceChannel] is deleted in a guild. + * + * @see Channel Delete + */ public class VoiceChannelDeleteEvent( override val channel: VoiceChannel, override val shard: Int, @@ -60,6 +90,11 @@ public class VoiceChannelDeleteEvent( } } +/** + * The event dispatched when a [StageChannel] is deleted in a guild. + * + * @see Channel Delete + */ public class StageChannelDeleteEvent( override val channel: StageChannel, override val shard: Int, @@ -70,6 +105,11 @@ public class StageChannelDeleteEvent( } } +/** + * The event dispatched when an Unknown [Channel] is deleted in a guild. + * + * @see Channel Delete + */ public class UnknownChannelDeleteEvent( override val channel: Channel, override val shard: Int, diff --git a/core/src/main/kotlin/event/channel/ChannelPinsUpdateEvent.kt b/core/src/main/kotlin/event/channel/ChannelPinsUpdateEvent.kt index 41cd3e2a0d0d..5cf19fb1622b 100644 --- a/core/src/main/kotlin/event/channel/ChannelPinsUpdateEvent.kt +++ b/core/src/main/kotlin/event/channel/ChannelPinsUpdateEvent.kt @@ -24,6 +24,8 @@ import kotlinx.datetime.Instant * @property shard The shard for the event * @property customContext Any custom context provided * @property supplier The entity supplier to use for the event + * + * @see Channel Pins Update */ public class ChannelPinsUpdateEvent( public val data: ChannelPinsUpdateEventData, diff --git a/core/src/main/kotlin/event/channel/ChannelUpdateEvent.kt b/core/src/main/kotlin/event/channel/ChannelUpdateEvent.kt index 1d1f85df97a4..b72921d23933 100644 --- a/core/src/main/kotlin/event/channel/ChannelUpdateEvent.kt +++ b/core/src/main/kotlin/event/channel/ChannelUpdateEvent.kt @@ -4,7 +4,13 @@ import dev.kord.core.Kord import dev.kord.core.entity.channel.* import dev.kord.core.event.Event - +/** + * The event dispatched when a [Channel] is updated. + * + * The [old] [Channel] may be null unless it has been stored in the cache. + * + * @see Channel Update + */ public interface ChannelUpdateEvent : Event { public val channel: Channel public val old: Channel? @@ -12,6 +18,13 @@ public interface ChannelUpdateEvent : Event { get() = channel.kord } +/** + * The event dispatched when a [Category] is updated. + * + * The [old] [Category] may be null unless it has been stored in the cache. + * + * @see Channel Update + */ public class CategoryUpdateEvent( override val channel: Category, override val old: Category?, @@ -23,6 +36,13 @@ public class CategoryUpdateEvent( } } +/** + * The event dispatched when a [DmChannel] is updated. + * + * The [old] [DmChannel] may be null unless it has been stored in the cache. + * + * @see Channel Update + */ public class DMChannelUpdateEvent( override val channel: DmChannel, override val old: DmChannel?, @@ -34,6 +54,15 @@ public class DMChannelUpdateEvent( } } +/** + * The event dispatched when a [NewsChannel] is updated. + * + * The [NewsChannel] may have been turned into [TextChannel]. + * + * The [old] [NewsChannel] may be null unless it has been stored in the cache. + * + * @see Channel Update + */ public class NewsChannelUpdateEvent( override val channel: NewsChannel, override val old: NewsChannel?, @@ -45,6 +74,15 @@ public class NewsChannelUpdateEvent( } } +/** + * The event dispatched when a [TextChannel] is updated. + * + * The [TextChannel] may have been turned into a [NewsChannel]. + * + * The [old] [TextChannel] may be null unless it has been stored in the cache. + * + * @see Channel Update + */ public class TextChannelUpdateEvent( override val channel: TextChannel, override val old: TextChannel?, @@ -56,6 +94,13 @@ public class TextChannelUpdateEvent( } } +/** + * The event dispatched when a [VoiceChannel] is updated. + * + * The [old] [VoiceChannel] may be null unless it has been stored in the cache. + * + * @see Channel Update + */ public class VoiceChannelUpdateEvent( override val channel: VoiceChannel, override val old: VoiceChannel?, @@ -67,7 +112,13 @@ public class VoiceChannelUpdateEvent( } } - +/** + * The event dispatched when a [StageChannel] is updated. + * + * The [old] [StageChannel] may be null unless it has been stored in the cache. + * + * @see Channel Update + */ public class StageChannelUpdateEvent( override val channel: StageChannel, override val old: StageChannel?, @@ -79,6 +130,13 @@ public class StageChannelUpdateEvent( } } +/** + * The event dispatched when an Unknown [Channel] is updated. + * + * The [old] Unknown [Channel] may be null unless it has been stored in the cache. + * + * @see Channel Update + */ public class UnknownChannelUpdateEvent( override val channel: Channel, override val old: Channel?, diff --git a/core/src/main/kotlin/event/channel/TypingStartEvent.kt b/core/src/main/kotlin/event/channel/TypingStartEvent.kt index f738c270cd29..81b2f5c4b68f 100644 --- a/core/src/main/kotlin/event/channel/TypingStartEvent.kt +++ b/core/src/main/kotlin/event/channel/TypingStartEvent.kt @@ -27,6 +27,8 @@ import kotlinx.datetime.Instant * @property shard The shard for the event * @property customContext Any custom context provided * @property supplier The entity supplier to use for the event + * + * @see Typing Start */ public class TypingStartEvent( public val data: TypingStartEventData, @@ -35,6 +37,7 @@ public class TypingStartEvent( override val customContext: Any?, override val supplier: EntitySupplier = kord.defaultSupplier, ) : Event, Strategizable { + /** * The ID of the channel that triggered the event. */ diff --git a/core/src/main/kotlin/event/channel/thread/ThreadCreateEvent.kt b/core/src/main/kotlin/event/channel/thread/ThreadCreateEvent.kt index 8a38ec1230e5..980c316cbcff 100644 --- a/core/src/main/kotlin/event/channel/thread/ThreadCreateEvent.kt +++ b/core/src/main/kotlin/event/channel/thread/ThreadCreateEvent.kt @@ -5,11 +5,20 @@ import dev.kord.core.entity.channel.thread.TextChannelThread import dev.kord.core.entity.channel.thread.ThreadChannel import dev.kord.core.event.channel.ChannelCreateEvent +/** + * The event dispatched when a [ThreadChannel] is created in a guild. + * + * @see Thread Create + */ public sealed interface ThreadChannelCreateEvent : ChannelCreateEvent { override val channel: ThreadChannel } - +/** + * The event dispatched when a [TextChannelThread] is created in a guild. + * + * @see Thread Create + */ public class TextChannelThreadCreateEvent( override val channel: TextChannelThread, override val shard: Int, @@ -20,7 +29,11 @@ public class TextChannelThreadCreateEvent( } } - +/** + * The event dispatched when a [NewsChannelThread] is created in a guild. + * + * @see Thread Create + */ public class NewsChannelThreadCreateEvent( override val channel: NewsChannelThread, override val shard: Int, @@ -31,6 +44,11 @@ public class NewsChannelThreadCreateEvent( } } +/** + * The event dispatched when an Unknown [ThreadChannel] is created in a guild. + * + * @see Thread Create + */ public class UnknownChannelThreadCreateEvent( override val channel: ThreadChannel, override val shard: Int, diff --git a/core/src/main/kotlin/event/channel/thread/ThreadDeleteEvent.kt b/core/src/main/kotlin/event/channel/thread/ThreadDeleteEvent.kt index 0135b492d9b8..7f5a8660ecb8 100644 --- a/core/src/main/kotlin/event/channel/thread/ThreadDeleteEvent.kt +++ b/core/src/main/kotlin/event/channel/thread/ThreadDeleteEvent.kt @@ -7,6 +7,11 @@ import dev.kord.core.entity.channel.thread.TextChannelThread import dev.kord.core.entity.channel.thread.ThreadChannel import dev.kord.core.event.Event +/** + * The event dispatched when a [ThreadChannel] is deleted in a guild. + * + * @see Thread Delete + */ public sealed interface ThreadChannelDeleteEvent : Event { public val channel: DeletedThreadChannel @@ -17,7 +22,11 @@ public sealed interface ThreadChannelDeleteEvent : Event { } - +/** + * The event dispatched when a [TextChannelThread] is deleted in a guild. + * + * @see Thread Delete + */ public class TextChannelThreadDeleteEvent( override val channel: DeletedThreadChannel, override val old: TextChannelThread?, @@ -29,7 +38,11 @@ public class TextChannelThreadDeleteEvent( } } - +/** + * The event dispatched when a [NewsChannelThread] is deleted in a guild. + * + * @see Thread Delete + */ public class NewsChannelThreadDeleteEvent( override val channel: DeletedThreadChannel, override val old: NewsChannelThread?, @@ -41,7 +54,11 @@ public class NewsChannelThreadDeleteEvent( } } - +/** + * The event dispatched when an Unknown [ThreadChannel] is deleted in a guild. + * + * @see Thread Delete + */ public class UnknownChannelThreadDeleteEvent( override val channel: DeletedThreadChannel, override val old: ThreadChannel?, diff --git a/core/src/main/kotlin/event/channel/thread/ThreadListSyncEvent.kt b/core/src/main/kotlin/event/channel/thread/ThreadListSyncEvent.kt index 103e3beac159..7edaace0a673 100644 --- a/core/src/main/kotlin/event/channel/thread/ThreadListSyncEvent.kt +++ b/core/src/main/kotlin/event/channel/thread/ThreadListSyncEvent.kt @@ -2,6 +2,7 @@ package dev.kord.core.event.channel.thread import dev.kord.common.entity.Snowflake import dev.kord.common.entity.optional.orEmpty +import dev.kord.common.exception.RequestException import dev.kord.core.Kord import dev.kord.core.behavior.GuildBehavior import dev.kord.core.behavior.channel.threads.ThreadParentChannelBehavior @@ -13,6 +14,7 @@ import dev.kord.core.entity.channel.TopGuildChannel import dev.kord.core.entity.channel.thread.ThreadChannel import dev.kord.core.entity.channel.thread.ThreadMember import dev.kord.core.event.Event +import dev.kord.core.exception.EntityNotFoundException import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy import kotlinx.coroutines.flow.Flow @@ -26,13 +28,18 @@ public class ThreadListSyncEvent( override val customContext: Any?, override val supplier: EntitySupplier = kord.defaultSupplier, ) : Event, Strategizable { - + /** + * The ID of the guild that triggered the event. + */ public val guildId: Snowflake get() = data.guildId + /** + * The [Guild][GuildBehavior] that triggered the event. + */ public val guild: GuildBehavior get() = GuildBehavior(guildId, kord) /** - * the parent channel ids whose threads are being synced. + * The parent channel ids whose threads are being synced. * If empty, then threads were synced for the entire guild. */ public val channelIds: List get() = data.channelIds.orEmpty() @@ -57,18 +64,36 @@ public class ThreadListSyncEvent( */ public val members: List get() = data.members.map { ThreadMember(it, kord) } + /** + * Requests to get the [Guild] for the event + * + * @throws RequestException if something went wrong while retrieving the guild. + * @throws EntityNotFoundException if the guild is null. + */ + // TODO Make this expression body syntax? Maybe another PR? public suspend fun getGuild(): Guild { return supplier.getGuild(guildId) } + /** + * Requests to get the [Guild] for the event, returns `null` when the guild isn't present. + * + * @throws RequestException if something went wrong while retrieving the guild. + */ public suspend fun getGuildOrNull(): Guild? { return supplier.getGuildOrNull(guildId) } + /** + * Requests to get the channels as a [Flow] of [TopGuildChannel]s for a guild + */ public suspend fun getChannels(): Flow { return supplier.getGuildChannels(guildId).filter { it.id in channelIds } } + /** + * Returns a copy of this class with a new [supplier] provided by the [strategy]. + */ override fun withStrategy(strategy: EntitySupplyStrategy<*>): ThreadListSyncEvent = ThreadListSyncEvent(data, kord, shard, customContext, strategy.supply(kord)) } diff --git a/core/src/main/kotlin/event/channel/thread/ThreadUpdateEvent.kt b/core/src/main/kotlin/event/channel/thread/ThreadUpdateEvent.kt index 7bbe86dda5d5..72fb75c724ff 100644 --- a/core/src/main/kotlin/event/channel/thread/ThreadUpdateEvent.kt +++ b/core/src/main/kotlin/event/channel/thread/ThreadUpdateEvent.kt @@ -5,11 +5,20 @@ import dev.kord.core.entity.channel.thread.TextChannelThread import dev.kord.core.entity.channel.thread.ThreadChannel import dev.kord.core.event.channel.ChannelUpdateEvent +/** + * The event dispatched when a [ThreadChannel] is updated in a guild. + * + * @see Thread Update + */ public sealed interface ThreadUpdateEvent : ChannelUpdateEvent { override val channel: ThreadChannel } - +/** + * The event dispatched when a [TextChannelThread] is updated in a guild. + * + * @see Thread Update + */ public class TextChannelThreadUpdateEvent( override val channel: TextChannelThread, override val old: TextChannelThread?, @@ -21,7 +30,11 @@ public class TextChannelThreadUpdateEvent( } } - +/** + * The event dispatched when a [NewsChannelThread] is updated in a guild. + * + * @see Thread Update + */ public class NewsChannelThreadUpdateEvent( override val channel: NewsChannelThread, override val old: NewsChannelThread?, @@ -33,7 +46,11 @@ public class NewsChannelThreadUpdateEvent( } } - +/** + * The event dispatched when an Unknown [ThreadChannel] is updated in a guild. + * + * @see Thread Update + */ public class UnknownChannelThreadUpdateEvent( override val channel: ThreadChannel, override val old: ThreadChannel?, From 5c2bac44a8073d8f579d4d9c6b96a45bd2d5183f Mon Sep 17 00:00:00 2001 From: NoComment1105 Date: Thu, 24 Nov 2022 15:18:33 +0000 Subject: [PATCH 03/17] Documents Documents Documents --- .../AutoModerationActionExecutionEventData.kt | 5 ++++ .../event/channel/ChannelCreateEvent.kt | 16 +++++----- .../event/channel/ChannelDeleteEvent.kt | 16 +++++----- .../event/channel/ChannelPinsUpdateEvent.kt | 12 ++++---- .../event/channel/ChannelUpdateEvent.kt | 26 ++++++++--------- .../kotlin/event/channel/TypingStartEvent.kt | 8 ++--- .../data/ChannelPinsUpdateEventData.kt | 5 ++++ .../channel/data/TypingStartEventData.kt | 5 ++++ .../event/channel/thread/ThreadCreateEvent.kt | 8 ++--- .../event/channel/thread/ThreadDeleteEvent.kt | 8 ++--- .../channel/thread/ThreadListSyncEvent.kt | 14 +++++++-- .../channel/thread/ThreadMemberUpdateEvent.kt | 7 +++++ .../thread/ThreadMembersUpdateEvent.kt | 20 +++++++++++++ .../event/channel/thread/ThreadUpdateEvent.kt | 8 ++--- core/src/main/kotlin/event/gateway/Events.kt | 20 +++++++++++++ .../main/kotlin/event/guild/BanAddEvent.kt | 3 ++ .../main/kotlin/event/guild/BanRemoveEvent.kt | 16 ++++++++++ .../kotlin/event/guild/EmojisUpdateEvent.kt | 16 ++++++++++ .../guild/GuildScheduledEventCreateEvent.kt | 2 +- .../guild/GuildScheduledEventDeleteEvent.kt | 2 +- .../guild/GuildScheduledEventUpdateEvent.kt | 2 +- .../guild/GuildScheduledEventUserEvent.kt | 29 +++++++++++++++++-- 22 files changed, 185 insertions(+), 63 deletions(-) diff --git a/core/src/main/kotlin/event/automoderation/data/AutoModerationActionExecutionEventData.kt b/core/src/main/kotlin/event/automoderation/data/AutoModerationActionExecutionEventData.kt index a5f50c4a9cbb..76fdf72078c0 100644 --- a/core/src/main/kotlin/event/automoderation/data/AutoModerationActionExecutionEventData.kt +++ b/core/src/main/kotlin/event/automoderation/data/AutoModerationActionExecutionEventData.kt @@ -7,6 +7,11 @@ import dev.kord.core.cache.data.AutoModerationActionData import dev.kord.gateway.DiscordAutoModerationActionExecution import kotlinx.serialization.Serializable +/** + * The data for the event dispatched when an auto-moderation action is executed. + * + * See [Auto moderation action execution](https://discord.com/developers/docs/topics/gateway-events#auto-moderation-action-execution) + */ @Serializable public data class AutoModerationActionExecutionEventData( val guildId: Snowflake, diff --git a/core/src/main/kotlin/event/channel/ChannelCreateEvent.kt b/core/src/main/kotlin/event/channel/ChannelCreateEvent.kt index a539f7a81315..9ba682bfeeac 100644 --- a/core/src/main/kotlin/event/channel/ChannelCreateEvent.kt +++ b/core/src/main/kotlin/event/channel/ChannelCreateEvent.kt @@ -7,7 +7,7 @@ import dev.kord.core.event.Event /** * The event dispatched when a [Channel] is created in a guild. * - * @see Channel Create + * See [Channel Create](https://discord.com/developers/docs/topics/gateway-events#channel-create) */ public interface ChannelCreateEvent : Event { public val channel: Channel @@ -18,7 +18,7 @@ public interface ChannelCreateEvent : Event { /** * The event dispatched when a [Category] is created in a guild. * - * @see Channel Create + * See [Channel Create](https://discord.com/developers/docs/topics/gateway-events#channel-create) */ public class CategoryCreateEvent( override val channel: Category, @@ -33,7 +33,7 @@ public class CategoryCreateEvent( /** * The event dispatched when a [DmChannel] is created in a guild. * - * @see Channel Create + * See [Channel Create](https://discord.com/developers/docs/topics/gateway-events#channel-create) */ public class DMChannelCreateEvent( override val channel: DmChannel, @@ -48,7 +48,7 @@ public class DMChannelCreateEvent( /** * The event dispatched when a [NewsChannel] is created in a guild. * - * @see Channel Create + * See [Channel Create](https://discord.com/developers/docs/topics/gateway-events#channel-create) */ public class NewsChannelCreateEvent( override val channel: NewsChannel, @@ -63,7 +63,7 @@ public class NewsChannelCreateEvent( /** * The event dispatched when a [TextChannel] is created in a guild. * - * @see Channel Create + * See [Channel Create](https://discord.com/developers/docs/topics/gateway-events#channel-create) */ public class TextChannelCreateEvent( override val channel: TextChannel, @@ -78,7 +78,7 @@ public class TextChannelCreateEvent( /** * The event dispatched when a [VoiceChannel] is created in a guild. * - * @see Channel Create + * See [Channel Create](https://discord.com/developers/docs/topics/gateway-events#channel-create) */ public class VoiceChannelCreateEvent( override val channel: VoiceChannel, @@ -93,7 +93,7 @@ public class VoiceChannelCreateEvent( /** * The event dispatched when a [StageChannel] is created in a guild. * - * @see Channel Create + * See [Channel Create](https://discord.com/developers/docs/topics/gateway-events#channel-create) */ public class StageChannelCreateEvent( override val channel: StageChannel, @@ -108,7 +108,7 @@ public class StageChannelCreateEvent( /** * The event dispatched when an Unknown [Channel] is created in a guild. * - * @see Channel Create + * See [Channel Create](https://discord.com/developers/docs/topics/gateway-events#channel-create) */ public class UnknownChannelCreateEvent( override val channel: Channel, diff --git a/core/src/main/kotlin/event/channel/ChannelDeleteEvent.kt b/core/src/main/kotlin/event/channel/ChannelDeleteEvent.kt index abf0dcedffdf..db3a9962fd6c 100644 --- a/core/src/main/kotlin/event/channel/ChannelDeleteEvent.kt +++ b/core/src/main/kotlin/event/channel/ChannelDeleteEvent.kt @@ -7,7 +7,7 @@ import dev.kord.core.event.Event /** * The event dispatched when a [Channel] is deleted in a guild. * - * @see Channel Delete + * See [Channel Delete](https://discord.com/developers/docs/topics/gateway-events#channel-delete) */ public interface ChannelDeleteEvent : Event { public val channel: Channel @@ -18,7 +18,7 @@ public interface ChannelDeleteEvent : Event { /** * The event dispatched when a [Category] is deleted in a guild. * - * @see Channel Delete + * See [Channel Delete](https://discord.com/developers/docs/topics/gateway-events#channel-delete) */ public class CategoryDeleteEvent( override val channel: Category, @@ -33,7 +33,7 @@ public class CategoryDeleteEvent( /** * The event dispatched when a [DmChannel] is deleted in a guild. * - * @see Channel Delete + * See [Channel Delete](https://discord.com/developers/docs/topics/gateway-events#channel-delete) */ public class DMChannelDeleteEvent( override val channel: DmChannel, @@ -48,7 +48,7 @@ public class DMChannelDeleteEvent( /** * The event dispatched when a [NewsChannel] is deleted in a guild. * - * @see Channel Delete + * See [Channel Delete](https://discord.com/developers/docs/topics/gateway-events#channel-delete) */ public class NewsChannelDeleteEvent( override val channel: NewsChannel, @@ -63,7 +63,7 @@ public class NewsChannelDeleteEvent( /** * The event dispatched when a [TextChannel] is deleted in a guild. * - * @see Channel Delete + * See [Channel Delete](https://discord.com/developers/docs/topics/gateway-events#channel-delete) */ public class TextChannelDeleteEvent( override val channel: TextChannel, @@ -78,7 +78,7 @@ public class TextChannelDeleteEvent( /** * The event dispatched when a [VoiceChannel] is deleted in a guild. * - * @see Channel Delete + * See [Channel Delete](https://discord.com/developers/docs/topics/gateway-events#channel-delete) */ public class VoiceChannelDeleteEvent( override val channel: VoiceChannel, @@ -93,7 +93,7 @@ public class VoiceChannelDeleteEvent( /** * The event dispatched when a [StageChannel] is deleted in a guild. * - * @see Channel Delete + * See [Channel Delete](https://discord.com/developers/docs/topics/gateway-events#channel-delete) */ public class StageChannelDeleteEvent( override val channel: StageChannel, @@ -108,7 +108,7 @@ public class StageChannelDeleteEvent( /** * The event dispatched when an Unknown [Channel] is deleted in a guild. * - * @see Channel Delete + * See [Channel Delete](https://discord.com/developers/docs/topics/gateway-events#channel-delete) */ public class UnknownChannelDeleteEvent( override val channel: Channel, diff --git a/core/src/main/kotlin/event/channel/ChannelPinsUpdateEvent.kt b/core/src/main/kotlin/event/channel/ChannelPinsUpdateEvent.kt index 5cf19fb1622b..c6f2cbdcfc77 100644 --- a/core/src/main/kotlin/event/channel/ChannelPinsUpdateEvent.kt +++ b/core/src/main/kotlin/event/channel/ChannelPinsUpdateEvent.kt @@ -17,15 +17,13 @@ import dev.kord.core.supplier.getChannelOfOrNull import kotlinx.datetime.Instant /** - * The event of a channels Pins being updated. + * The event dispatched when a message is pinned or unpinned in a text channel. * - * @property data The data associated with the event - * @property kord The Kord Instance - * @property shard The shard for the event - * @property customContext Any custom context provided - * @property supplier The entity supplier to use for the event + * This event is not sent when a pinned message is deleted. + * + * See [Channel Pins Update](https://discord.com/developers/docs/topics/gateway-events#channel-pins-update) * - * @see Channel Pins Update + * @property data The data associated with the event */ public class ChannelPinsUpdateEvent( public val data: ChannelPinsUpdateEventData, diff --git a/core/src/main/kotlin/event/channel/ChannelUpdateEvent.kt b/core/src/main/kotlin/event/channel/ChannelUpdateEvent.kt index b72921d23933..15fd9e7bbeff 100644 --- a/core/src/main/kotlin/event/channel/ChannelUpdateEvent.kt +++ b/core/src/main/kotlin/event/channel/ChannelUpdateEvent.kt @@ -7,9 +7,9 @@ import dev.kord.core.event.Event /** * The event dispatched when a [Channel] is updated. * - * The [old] [Channel] may be null unless it has been stored in the cache. + * The [old][old] [Channel] may be null unless it has been stored in the cache. * - * @see Channel Update + * See [Channel Update](https://discord.com/developers/docs/topics/gateway-events#channel-update) */ public interface ChannelUpdateEvent : Event { public val channel: Channel @@ -21,9 +21,9 @@ public interface ChannelUpdateEvent : Event { /** * The event dispatched when a [Category] is updated. * - * The [old] [Category] may be null unless it has been stored in the cache. + * The [old][old] [Category] may be null unless it has been stored in the cache. * - * @see Channel Update + * See [Channel Update](https://discord.com/developers/docs/topics/gateway-events#channel-update) */ public class CategoryUpdateEvent( override val channel: Category, @@ -39,9 +39,9 @@ public class CategoryUpdateEvent( /** * The event dispatched when a [DmChannel] is updated. * - * The [old] [DmChannel] may be null unless it has been stored in the cache. + * The [old][old] [DmChannel] may be null unless it has been stored in the cache. * - * @see Channel Update + * See [Channel Update](https://discord.com/developers/docs/topics/gateway-events#channel-update) */ public class DMChannelUpdateEvent( override val channel: DmChannel, @@ -59,9 +59,9 @@ public class DMChannelUpdateEvent( * * The [NewsChannel] may have been turned into [TextChannel]. * - * The [old] [NewsChannel] may be null unless it has been stored in the cache. + * The [old][old] [NewsChannel] may be null unless it has been stored in the cache. * - * @see Channel Update + * See [Channel Update](https://discord.com/developers/docs/topics/gateway-events#channel-update) */ public class NewsChannelUpdateEvent( override val channel: NewsChannel, @@ -79,9 +79,9 @@ public class NewsChannelUpdateEvent( * * The [TextChannel] may have been turned into a [NewsChannel]. * - * The [old] [TextChannel] may be null unless it has been stored in the cache. + * The [old][old] [TextChannel] may be null unless it has been stored in the cache. * - * @see Channel Update + * See [Channel Update](https://discord.com/developers/docs/topics/gateway-events#channel-update) */ public class TextChannelUpdateEvent( override val channel: TextChannel, @@ -99,7 +99,7 @@ public class TextChannelUpdateEvent( * * The [old] [VoiceChannel] may be null unless it has been stored in the cache. * - * @see Channel Update + * See [Channel Update](https://discord.com/developers/docs/topics/gateway-events#channel-update) */ public class VoiceChannelUpdateEvent( override val channel: VoiceChannel, @@ -117,7 +117,7 @@ public class VoiceChannelUpdateEvent( * * The [old] [StageChannel] may be null unless it has been stored in the cache. * - * @see Channel Update + * See [Channel Update](https://discord.com/developers/docs/topics/gateway-events#channel-update) */ public class StageChannelUpdateEvent( override val channel: StageChannel, @@ -135,7 +135,7 @@ public class StageChannelUpdateEvent( * * The [old] Unknown [Channel] may be null unless it has been stored in the cache. * - * @see Channel Update + * See [Channel Update](https://discord.com/developers/docs/topics/gateway-events#channel-update) */ public class UnknownChannelUpdateEvent( override val channel: Channel, diff --git a/core/src/main/kotlin/event/channel/TypingStartEvent.kt b/core/src/main/kotlin/event/channel/TypingStartEvent.kt index 81b2f5c4b68f..38a52b3e9736 100644 --- a/core/src/main/kotlin/event/channel/TypingStartEvent.kt +++ b/core/src/main/kotlin/event/channel/TypingStartEvent.kt @@ -20,15 +20,11 @@ import dev.kord.core.supplier.getChannelOfOrNull import kotlinx.datetime.Instant /** - * The event that typing begins in a channel. + * The event that is dispatched when a user starts typing in a channel. * * @property data The data associated with the event - * @property kord The Kord Instance - * @property shard The shard for the event - * @property customContext Any custom context provided - * @property supplier The entity supplier to use for the event * - * @see Typing Start + * See [Typing Start](https://discord.com/developers/docs/topics/gateway-events#typing-start) */ public class TypingStartEvent( public val data: TypingStartEventData, diff --git a/core/src/main/kotlin/event/channel/data/ChannelPinsUpdateEventData.kt b/core/src/main/kotlin/event/channel/data/ChannelPinsUpdateEventData.kt index 15b7623a0eae..842faf348bd2 100644 --- a/core/src/main/kotlin/event/channel/data/ChannelPinsUpdateEventData.kt +++ b/core/src/main/kotlin/event/channel/data/ChannelPinsUpdateEventData.kt @@ -7,6 +7,11 @@ import dev.kord.common.entity.optional.OptionalSnowflake import kotlinx.datetime.Instant import kotlinx.serialization.Serializable +/** + * The data for the event dispatched when a message is pinned or unpinned from a text channel. + * + * See [Channel Pins Update](https://discord.com/developers/docs/topics/gateway-events#channel-pins-update) + */ @Serializable public data class ChannelPinsUpdateEventData( val guildId: OptionalSnowflake = OptionalSnowflake.Missing, diff --git a/core/src/main/kotlin/event/channel/data/TypingStartEventData.kt b/core/src/main/kotlin/event/channel/data/TypingStartEventData.kt index 2318b9683289..6c1bdc46fa10 100644 --- a/core/src/main/kotlin/event/channel/data/TypingStartEventData.kt +++ b/core/src/main/kotlin/event/channel/data/TypingStartEventData.kt @@ -9,6 +9,11 @@ import dev.kord.common.serialization.InstantInEpochSecondsSerializer import kotlinx.datetime.Instant import kotlinx.serialization.Serializable +/** + * The data for the event dispatched when a user starts typing in a channel. + * + * See [Typing Start](https://discord.com/developers/docs/topics/gateway-events#typing-start) + */ @Serializable public data class TypingStartEventData( val channelId: Snowflake, diff --git a/core/src/main/kotlin/event/channel/thread/ThreadCreateEvent.kt b/core/src/main/kotlin/event/channel/thread/ThreadCreateEvent.kt index 980c316cbcff..e7f6ec8022b9 100644 --- a/core/src/main/kotlin/event/channel/thread/ThreadCreateEvent.kt +++ b/core/src/main/kotlin/event/channel/thread/ThreadCreateEvent.kt @@ -8,7 +8,7 @@ import dev.kord.core.event.channel.ChannelCreateEvent /** * The event dispatched when a [ThreadChannel] is created in a guild. * - * @see Thread Create + * See [Thread Create](https://discord.com/developers/docs/topics/gateway-events#thread-create) */ public sealed interface ThreadChannelCreateEvent : ChannelCreateEvent { override val channel: ThreadChannel @@ -17,7 +17,7 @@ public sealed interface ThreadChannelCreateEvent : ChannelCreateEvent { /** * The event dispatched when a [TextChannelThread] is created in a guild. * - * @see Thread Create + * See [Thread Create](https://discord.com/developers/docs/topics/gateway-events#thread-create) */ public class TextChannelThreadCreateEvent( override val channel: TextChannelThread, @@ -32,7 +32,7 @@ public class TextChannelThreadCreateEvent( /** * The event dispatched when a [NewsChannelThread] is created in a guild. * - * @see Thread Create + * See [Thread Create](https://discord.com/developers/docs/topics/gateway-events#thread-create) */ public class NewsChannelThreadCreateEvent( override val channel: NewsChannelThread, @@ -47,7 +47,7 @@ public class NewsChannelThreadCreateEvent( /** * The event dispatched when an Unknown [ThreadChannel] is created in a guild. * - * @see Thread Create + * See [Thread Create](https://discord.com/developers/docs/topics/gateway-events#thread-create) */ public class UnknownChannelThreadCreateEvent( override val channel: ThreadChannel, diff --git a/core/src/main/kotlin/event/channel/thread/ThreadDeleteEvent.kt b/core/src/main/kotlin/event/channel/thread/ThreadDeleteEvent.kt index 7f5a8660ecb8..d2366519c464 100644 --- a/core/src/main/kotlin/event/channel/thread/ThreadDeleteEvent.kt +++ b/core/src/main/kotlin/event/channel/thread/ThreadDeleteEvent.kt @@ -10,7 +10,7 @@ import dev.kord.core.event.Event /** * The event dispatched when a [ThreadChannel] is deleted in a guild. * - * @see Thread Delete + * See [Thread Delete](https://discord.com/developers/docs/topics/gateway-events#thread-delete) */ public sealed interface ThreadChannelDeleteEvent : Event { public val channel: DeletedThreadChannel @@ -25,7 +25,7 @@ public sealed interface ThreadChannelDeleteEvent : Event { /** * The event dispatched when a [TextChannelThread] is deleted in a guild. * - * @see Thread Delete + * See [Thread Delete](https://discord.com/developers/docs/topics/gateway-events#thread-delete) */ public class TextChannelThreadDeleteEvent( override val channel: DeletedThreadChannel, @@ -41,7 +41,7 @@ public class TextChannelThreadDeleteEvent( /** * The event dispatched when a [NewsChannelThread] is deleted in a guild. * - * @see Thread Delete + * See [Thread Delete](https://discord.com/developers/docs/topics/gateway-events#thread-delete) */ public class NewsChannelThreadDeleteEvent( override val channel: DeletedThreadChannel, @@ -57,7 +57,7 @@ public class NewsChannelThreadDeleteEvent( /** * The event dispatched when an Unknown [ThreadChannel] is deleted in a guild. * - * @see Thread Delete + * See [Thread Delete](https://discord.com/developers/docs/topics/gateway-events#thread-delete) */ public class UnknownChannelThreadDeleteEvent( override val channel: DeletedThreadChannel, diff --git a/core/src/main/kotlin/event/channel/thread/ThreadListSyncEvent.kt b/core/src/main/kotlin/event/channel/thread/ThreadListSyncEvent.kt index 7edaace0a673..a0f3aa6591ec 100644 --- a/core/src/main/kotlin/event/channel/thread/ThreadListSyncEvent.kt +++ b/core/src/main/kotlin/event/channel/thread/ThreadListSyncEvent.kt @@ -20,7 +20,13 @@ import dev.kord.core.supplier.EntitySupplyStrategy import kotlinx.coroutines.flow.Flow import kotlinx.coroutines.flow.filter - +/** + * The event dispatched when a Thread list is synced. + * + * See [Thread List Sync](https://discord.com/developers/docs/topics/gateway-events#thread-list-sync) + * + * @property data The data for the sync + */ public class ThreadListSyncEvent( public val data: ThreadListSyncData, override val kord: Kord, @@ -44,6 +50,9 @@ public class ThreadListSyncEvent( */ public val channelIds: List get() = data.channelIds.orEmpty() + /** + * The behavior of the channels that contain threads, if the [channelIds] list is not empty. + */ public val channelBehaviors: List get() = channelIds.map { ThreadParentChannelBehavior(guildId, it, kord) @@ -68,9 +77,8 @@ public class ThreadListSyncEvent( * Requests to get the [Guild] for the event * * @throws RequestException if something went wrong while retrieving the guild. - * @throws EntityNotFoundException if the guild is null. + * @throws EntityNotFoundException if the guild is `null`. */ - // TODO Make this expression body syntax? Maybe another PR? public suspend fun getGuild(): Guild { return supplier.getGuild(guildId) } diff --git a/core/src/main/kotlin/event/channel/thread/ThreadMemberUpdateEvent.kt b/core/src/main/kotlin/event/channel/thread/ThreadMemberUpdateEvent.kt index d9e6b84f930e..94d6ce13d899 100644 --- a/core/src/main/kotlin/event/channel/thread/ThreadMemberUpdateEvent.kt +++ b/core/src/main/kotlin/event/channel/thread/ThreadMemberUpdateEvent.kt @@ -4,6 +4,13 @@ import dev.kord.core.Kord import dev.kord.core.entity.channel.thread.ThreadMember import dev.kord.core.event.Event +/** + * The event dispatched when a [ThreadMember] for the current user is updated. + * + * See [Thread Member Update](https://discord.com/developers/docs/topics/gateway-events#thread-member-update) + * + * @property member The member that triggered the event + */ public class ThreadMemberUpdateEvent( public val member: ThreadMember, override val kord: Kord, diff --git a/core/src/main/kotlin/event/channel/thread/ThreadMembersUpdateEvent.kt b/core/src/main/kotlin/event/channel/thread/ThreadMembersUpdateEvent.kt index 0f9c1ecc5665..28ac2070a357 100644 --- a/core/src/main/kotlin/event/channel/thread/ThreadMembersUpdateEvent.kt +++ b/core/src/main/kotlin/event/channel/thread/ThreadMembersUpdateEvent.kt @@ -8,6 +8,11 @@ import dev.kord.core.cache.data.ThreadMembersUpdateEventData import dev.kord.core.entity.channel.thread.ThreadMember import dev.kord.core.event.Event +/** + * The event dispatched when a guild member is added or removed from a thread. + * + * See [Thread Members Update](https://discord.com/developers/docs/topics/gateway-events#thread-members-update) + */ public class ThreadMembersUpdateEvent( public val data: ThreadMembersUpdateEventData, override val kord: Kord, @@ -15,17 +20,32 @@ public class ThreadMembersUpdateEvent( override val customContext: Any?, ) : Event { + /** + * The ID of the thread that triggered the event. + */ public val id: Snowflake get() = data.id + /** + * The ID of the guild the event was triggered by. + */ public val guildId: Snowflake get() = data.guildId + /** + * The approximate number of members in this thread. Capped at 50 members. + */ public val memberCount: Int get() = data.memberCount + /** + * The [List] of users added to the thread in this event. + */ public val addedMembers: List get() = data.addedMembers.orEmpty().map { ThreadMember(it, kord) } + /** + * A [List] IDs for the users removed from the thread in this event, or empty if null. + */ public val removedMemberIds: List get() = data.removedMemberIds.orEmpty() public val removedMemberBehaviors: List diff --git a/core/src/main/kotlin/event/channel/thread/ThreadUpdateEvent.kt b/core/src/main/kotlin/event/channel/thread/ThreadUpdateEvent.kt index 72fb75c724ff..1de92e40e95a 100644 --- a/core/src/main/kotlin/event/channel/thread/ThreadUpdateEvent.kt +++ b/core/src/main/kotlin/event/channel/thread/ThreadUpdateEvent.kt @@ -8,7 +8,7 @@ import dev.kord.core.event.channel.ChannelUpdateEvent /** * The event dispatched when a [ThreadChannel] is updated in a guild. * - * @see Thread Update + * See [Thread Update](https://discord.com/developers/docs/topics/gateway-events#thread-update) */ public sealed interface ThreadUpdateEvent : ChannelUpdateEvent { override val channel: ThreadChannel @@ -17,7 +17,7 @@ public sealed interface ThreadUpdateEvent : ChannelUpdateEvent { /** * The event dispatched when a [TextChannelThread] is updated in a guild. * - * @see Thread Update + * See [Thread Update](https://discord.com/developers/docs/topics/gateway-events#thread-update) */ public class TextChannelThreadUpdateEvent( override val channel: TextChannelThread, @@ -33,7 +33,7 @@ public class TextChannelThreadUpdateEvent( /** * The event dispatched when a [NewsChannelThread] is updated in a guild. * - * @see Thread Update + * See [Thread Update](https://discord.com/developers/docs/topics/gateway-events#thread-update) */ public class NewsChannelThreadUpdateEvent( override val channel: NewsChannelThread, @@ -49,7 +49,7 @@ public class NewsChannelThreadUpdateEvent( /** * The event dispatched when an Unknown [ThreadChannel] is updated in a guild. * - * @see Thread Update + * See [Thread Update](https://discord.com/developers/docs/topics/gateway-events#thread-update) */ public class UnknownChannelThreadUpdateEvent( override val channel: ThreadChannel, diff --git a/core/src/main/kotlin/event/gateway/Events.kt b/core/src/main/kotlin/event/gateway/Events.kt index 90d30f156e17..6187c92d3524 100644 --- a/core/src/main/kotlin/event/gateway/Events.kt +++ b/core/src/main/kotlin/event/gateway/Events.kt @@ -15,8 +15,14 @@ import dev.kord.gateway.GatewayCloseCode import kotlinx.coroutines.flow.Flow import kotlinx.coroutines.flow.filter +/** + * A Gateway recieved an event. + */ public sealed class GatewayEvent : Event +/** + * The event dispatched when a bot connects to the Gateway. + */ public class ConnectEvent( override val kord: Kord, override val shard: Int, @@ -137,6 +143,9 @@ public sealed class DisconnectEvent : GatewayEvent() { } +/** + * The event sent after the bot sends a valid `Identify` payload. + */ public class ReadyEvent( public val gatewayVersion: Int, public val guildIds: Set, @@ -149,8 +158,16 @@ public class ReadyEvent( override val supplier: EntitySupplier = kord.defaultSupplier, ) : GatewayEvent(), Strategizable { + /** + * A set of all the [Guild]s the bot is in. + */ public val guilds: Set get() = guildIds.map { GuildBehavior(it, kord) }.toSet() + /** + * Requests to get a flow of all the [Guild]s the bot is in from the [supplier], filtered to those in the [guilds] set. + * + * @return A flow of [Guild]s the bot is in + */ public suspend fun getGuilds(): Flow = supplier.guilds.filter { it.id in guildIds } override fun withStrategy(strategy: EntitySupplyStrategy<*>): ReadyEvent = @@ -160,6 +177,9 @@ public class ReadyEvent( "sessionId='$sessionId', resumeGatewayUrl=$resumeGatewayUrl, kord=$kord, shard=$shard, supplier=$supplier)" } +/** + * The event sent when the bot is attempting to reconnect. + */ public class ResumedEvent( override val kord: Kord, override val shard: Int, diff --git a/core/src/main/kotlin/event/guild/BanAddEvent.kt b/core/src/main/kotlin/event/guild/BanAddEvent.kt index 0bdcb12d3adb..09f572b9e26f 100644 --- a/core/src/main/kotlin/event/guild/BanAddEvent.kt +++ b/core/src/main/kotlin/event/guild/BanAddEvent.kt @@ -23,6 +23,9 @@ public class BanAddEvent( override val kord: Kord get() = user.kord + /** + * The [Guild] this event was triggered from + */ public val guild: GuildBehavior get() = GuildBehavior(guildId, kord) /** diff --git a/core/src/main/kotlin/event/guild/BanRemoveEvent.kt b/core/src/main/kotlin/event/guild/BanRemoveEvent.kt index 83fe194bf84a..0df739578204 100644 --- a/core/src/main/kotlin/event/guild/BanRemoveEvent.kt +++ b/core/src/main/kotlin/event/guild/BanRemoveEvent.kt @@ -1,12 +1,14 @@ package dev.kord.core.event.guild import dev.kord.common.entity.Snowflake +import dev.kord.common.exception.RequestException import dev.kord.core.Kord import dev.kord.core.behavior.GuildBehavior import dev.kord.core.entity.Guild import dev.kord.core.entity.Strategizable import dev.kord.core.entity.User import dev.kord.core.event.Event +import dev.kord.core.exception.EntityNotFoundException import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy @@ -20,10 +22,24 @@ public class BanRemoveEvent( override val kord: Kord get() = user.kord + /** + * The [Guild] this event was triggered from. + */ public val guild: GuildBehavior get() = GuildBehavior(guildId, kord) + /** + * Requests to get the [Guild] this ban was removed from. + * + * @throws [RequestException] if anything went wrong during the request. + * @throws [EntityNotFoundException] if the guild wasn't present. + */ public suspend fun getGuild(): Guild = supplier.getGuild(guildId) + /** + * Requests to get the [Guild] this ban was removed from, or `null` if the guild wasnt' present + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getGuildOrNull(): Guild? = supplier.getGuildOrNull(guildId) override fun withStrategy(strategy: EntitySupplyStrategy<*>): BanRemoveEvent = diff --git a/core/src/main/kotlin/event/guild/EmojisUpdateEvent.kt b/core/src/main/kotlin/event/guild/EmojisUpdateEvent.kt index 6283da56823d..1ec436001722 100644 --- a/core/src/main/kotlin/event/guild/EmojisUpdateEvent.kt +++ b/core/src/main/kotlin/event/guild/EmojisUpdateEvent.kt @@ -1,12 +1,14 @@ package dev.kord.core.event.guild import dev.kord.common.entity.Snowflake +import dev.kord.common.exception.RequestException import dev.kord.core.Kord import dev.kord.core.behavior.GuildBehavior import dev.kord.core.entity.Guild import dev.kord.core.entity.GuildEmoji import dev.kord.core.entity.Strategizable import dev.kord.core.event.Event +import dev.kord.core.exception.EntityNotFoundException import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy @@ -20,10 +22,24 @@ public class EmojisUpdateEvent( override val supplier: EntitySupplier = kord.defaultSupplier, ) : Event, Strategizable { + /** + * The guild this event was triggered from. + */ public val guild: GuildBehavior get() = GuildBehavior(guildId, kord) + /** + * Requests to get the [Guild] this update was triggered from. + * + * @throws [RequestException] if anything went wrong during the request. + * @throws [EntityNotFoundException] if the guild wasn't present. + */ public suspend fun getGuild(): Guild = supplier.getGuild(guildId) + /** + * Requests to get the [Guild] this update was triggered from, or `null` if the guild wasn't present. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getGuildOrNull(): Guild? = supplier.getGuildOrNull(guildId) override fun withStrategy(strategy: EntitySupplyStrategy<*>): EmojisUpdateEvent = diff --git a/core/src/main/kotlin/event/guild/GuildScheduledEventCreateEvent.kt b/core/src/main/kotlin/event/guild/GuildScheduledEventCreateEvent.kt index e4e9d52cb864..947b60ec7941 100644 --- a/core/src/main/kotlin/event/guild/GuildScheduledEventCreateEvent.kt +++ b/core/src/main/kotlin/event/guild/GuildScheduledEventCreateEvent.kt @@ -6,7 +6,7 @@ import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy /** - * Event fired when a scheduled event got created. + * The event dispatched when a scheduled guild event was created. * * @see GuildScheduledEvent * @see GuildScheduledEventEvent diff --git a/core/src/main/kotlin/event/guild/GuildScheduledEventDeleteEvent.kt b/core/src/main/kotlin/event/guild/GuildScheduledEventDeleteEvent.kt index cec740bda846..5b468fdb033d 100644 --- a/core/src/main/kotlin/event/guild/GuildScheduledEventDeleteEvent.kt +++ b/core/src/main/kotlin/event/guild/GuildScheduledEventDeleteEvent.kt @@ -6,7 +6,7 @@ import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy /** - * Event fired when a scheduled event got deleted. + * The event dispatched when a scheduled guild event got deleted. * Use [GuildScheduledEvent.status] to know why the event got deleted. * * @see GuildScheduledEvent diff --git a/core/src/main/kotlin/event/guild/GuildScheduledEventUpdateEvent.kt b/core/src/main/kotlin/event/guild/GuildScheduledEventUpdateEvent.kt index 2e013605e0fb..d2afab9a0fbf 100644 --- a/core/src/main/kotlin/event/guild/GuildScheduledEventUpdateEvent.kt +++ b/core/src/main/kotlin/event/guild/GuildScheduledEventUpdateEvent.kt @@ -9,7 +9,7 @@ import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy /** - * Event fired if a [GuildScheduledEvent] gets updated. + * The event dispatched when a [GuildScheduledEvent] gets updated. * * @property scheduledEvent the updated event, for the old event use [oldEvent] * @property oldEvent the event that was in the cache before the update diff --git a/core/src/main/kotlin/event/guild/GuildScheduledEventUserEvent.kt b/core/src/main/kotlin/event/guild/GuildScheduledEventUserEvent.kt index 8a7d913e74d0..3c0877030eaa 100644 --- a/core/src/main/kotlin/event/guild/GuildScheduledEventUserEvent.kt +++ b/core/src/main/kotlin/event/guild/GuildScheduledEventUserEvent.kt @@ -8,15 +8,38 @@ import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy /** - * Sent when a user has [subscribed to][GuildScheduledEventUserAddEvent] or + * The event dispatched when a user has [subscribed to][GuildScheduledEventUserAddEvent] or * [unsubscribed from][GuildScheduledEventUserRemoveEvent] a [GuildScheduledEvent]. */ public sealed interface GuildScheduledEventUserEvent : Event, Strategizable { + /** + * The ID of the scheduled guild event + */ public val scheduledEventId: Snowflake + + /** + * The ID of the user that (un)subscribed from the event + */ public val userId: Snowflake + + /** + * The ID of the guild this event is in. + */ public val guildId: Snowflake + /** + * Requests to get the [User] that (un)subscribed to the event. + * + * @throws [RequestException] if anything went wrong during the request + * @throws [EntityNotFoundException] if the user was not present + */ public suspend fun getUser(): User = supplier.getUser(userId) + + /** + * Requests to get the [User] that (un)subscribed to the event, or `null` if the user wasn't present. + * + * @throws [RequestException] if anything went wrong during the request + */ public suspend fun getUserOrNull(): User? = supplier.getUserOrNull(userId) public suspend fun getMember(): Member = supplier.getMember(guildId, userId) @@ -32,7 +55,7 @@ public sealed interface GuildScheduledEventUserEvent : Event, Strategizable { override fun withStrategy(strategy: EntitySupplyStrategy<*>): GuildScheduledEventUserEvent } -/** Sent when a user has subscribed to a [GuildScheduledEvent]. */ +/** The event dispatched when a user has subscribed to a [GuildScheduledEvent]. */ public data class GuildScheduledEventUserAddEvent( override val scheduledEventId: Snowflake, override val userId: Snowflake, @@ -46,7 +69,7 @@ public data class GuildScheduledEventUserAddEvent( GuildScheduledEventUserAddEvent(scheduledEventId, userId, guildId, kord, shard, customContext, strategy.supply(kord)) } -/** Sent when a user has unsubscribed from a [GuildScheduledEvent]. */ +/** The event dispatched when a user has unsubscribed from a [GuildScheduledEvent]. */ public data class GuildScheduledEventUserRemoveEvent( override val scheduledEventId: Snowflake, override val userId: Snowflake, From e85b59798bc84165cb93acb17e5dc46814380dad Mon Sep 17 00:00:00 2001 From: NoComment1105 Date: Thu, 24 Nov 2022 17:16:46 +0000 Subject: [PATCH 04/17] More Docs yey --- .../AutoModerationActionExecutionEvent.kt | 2 + .../AutoModerationRuleConfigurationEvent.kt | 6 ++ .../thread/ThreadMembersUpdateEvent.kt | 5 +- .../main/kotlin/event/guild/BanAddEvent.kt | 2 +- .../main/kotlin/event/guild/BanRemoveEvent.kt | 2 +- .../kotlin/event/guild/EmojisUpdateEvent.kt | 7 +++ .../kotlin/event/guild/GuildCreateEvent.kt | 11 ++++ .../kotlin/event/guild/GuildDeleteEvent.kt | 7 +++ .../guild/GuildScheduledEventCreateEvent.kt | 2 + .../guild/GuildScheduledEventDeleteEvent.kt | 2 + .../guild/GuildScheduledEventUpdateEvent.kt | 2 + .../guild/GuildScheduledEventUserEvent.kt | 59 +++++++++++++++++-- .../kotlin/event/guild/GuildUpdateEvent.kt | 7 +++ .../event/guild/IntegrationsUpdateEvent.kt | 22 ++++++- .../kotlin/event/guild/InviteCreateEvent.kt | 18 +++--- .../kotlin/event/guild/InviteDeleteEvent.kt | 8 ++- .../kotlin/event/guild/MemberJoinEvent.kt | 24 ++++++++ .../kotlin/event/guild/MemberLeaveEvent.kt | 25 +++++++- .../kotlin/event/guild/MemberUpdateEvent.kt | 27 ++++++++- .../kotlin/event/guild/MembersChunkEvent.kt | 44 +++++++++++++- .../event/guild/VoiceServerUpdateEvent.kt | 23 +++++++- .../kotlin/event/guild/WebhookUpdateEvent.kt | 36 ++++++++++- 22 files changed, 317 insertions(+), 24 deletions(-) diff --git a/core/src/main/kotlin/event/automoderation/AutoModerationActionExecutionEvent.kt b/core/src/main/kotlin/event/automoderation/AutoModerationActionExecutionEvent.kt index d8f5eb909890..984444f722d3 100644 --- a/core/src/main/kotlin/event/automoderation/AutoModerationActionExecutionEvent.kt +++ b/core/src/main/kotlin/event/automoderation/AutoModerationActionExecutionEvent.kt @@ -25,6 +25,8 @@ import dev.kord.gateway.Intent.MessageContent * executed (e.g. when a message is [blocked][BlockMessageAutoModerationAction]). * * This event is only sent to bot users which have the [ManageGuild] permission. + * + * See [Auto moderation action execution event](https://discord.com/developers/docs/topics/gateway-events#auto-moderation-action-execution) */ public class AutoModerationActionExecutionEvent( public val data: AutoModerationActionExecutionEventData, diff --git a/core/src/main/kotlin/event/automoderation/AutoModerationRuleConfigurationEvent.kt b/core/src/main/kotlin/event/automoderation/AutoModerationRuleConfigurationEvent.kt index 0e13e0454619..80d929b95563 100644 --- a/core/src/main/kotlin/event/automoderation/AutoModerationRuleConfigurationEvent.kt +++ b/core/src/main/kotlin/event/automoderation/AutoModerationRuleConfigurationEvent.kt @@ -31,6 +31,8 @@ public sealed interface AutoModerationRuleConfigurationEvent : AutoModerationEve * An [AutoModerationRuleConfigurationEvent] that is sent when an [AutoModerationRule] is created. * * This event is only sent to bot users which have the [ManageGuild] permission. + * + * See [Auto moderation rule create](https://discord.com/developers/docs/topics/gateway-events#auto-moderation-rule-create) */ public class AutoModerationRuleCreateEvent( /** The [AutoModerationRule] that was created. */ @@ -52,6 +54,8 @@ public class AutoModerationRuleCreateEvent( * An [AutoModerationRuleConfigurationEvent] that is sent when an [AutoModerationRule] is updated. * * This event is only sent to bot users which have the [ManageGuild] permission. + * + * See [Auto moderation rule update](https://discord.com/developers/docs/topics/gateway-events#auto-moderation-rule-update) */ public class AutoModerationRuleUpdateEvent( /** The [AutoModerationRule] that was updated. */ @@ -75,6 +79,8 @@ public class AutoModerationRuleUpdateEvent( * An [AutoModerationRuleConfigurationEvent] that is sent when an [AutoModerationRule] is deleted. * * This event is only sent to bot users which have the [ManageGuild] permission. + * + * See [Auto moderation rule delete](https://discord.com/developers/docs/topics/gateway-events#auto-moderation-rule-delete) */ public class AutoModerationRuleDeleteEvent( /** The [AutoModerationRule] that was deleted. */ diff --git a/core/src/main/kotlin/event/channel/thread/ThreadMembersUpdateEvent.kt b/core/src/main/kotlin/event/channel/thread/ThreadMembersUpdateEvent.kt index 28ac2070a357..9bc0152ea616 100644 --- a/core/src/main/kotlin/event/channel/thread/ThreadMembersUpdateEvent.kt +++ b/core/src/main/kotlin/event/channel/thread/ThreadMembersUpdateEvent.kt @@ -44,10 +44,13 @@ public class ThreadMembersUpdateEvent( } /** - * A [List] IDs for the users removed from the thread in this event, or empty if null. + * The [List] of IDs for the users removed from the thread in this event, or empty if null. */ public val removedMemberIds: List get() = data.removedMemberIds.orEmpty() + /** + * The [List] of users removed from the thread in this event as [MemberBehavior] + */ public val removedMemberBehaviors: List get() = removedMemberIds.map { MemberBehavior(guildId, it, kord) diff --git a/core/src/main/kotlin/event/guild/BanAddEvent.kt b/core/src/main/kotlin/event/guild/BanAddEvent.kt index 09f572b9e26f..79fed38b1d64 100644 --- a/core/src/main/kotlin/event/guild/BanAddEvent.kt +++ b/core/src/main/kotlin/event/guild/BanAddEvent.kt @@ -38,7 +38,7 @@ public class BanAddEvent( /** * Requests to get the [Guild] this ban happened in, - * returns null if the guild isn't present. + * returns `null` if the guild isn't present. * * @throws [RequestException] if anything went wrong during the request. */ diff --git a/core/src/main/kotlin/event/guild/BanRemoveEvent.kt b/core/src/main/kotlin/event/guild/BanRemoveEvent.kt index 0df739578204..34f994825057 100644 --- a/core/src/main/kotlin/event/guild/BanRemoveEvent.kt +++ b/core/src/main/kotlin/event/guild/BanRemoveEvent.kt @@ -36,7 +36,7 @@ public class BanRemoveEvent( public suspend fun getGuild(): Guild = supplier.getGuild(guildId) /** - * Requests to get the [Guild] this ban was removed from, or `null` if the guild wasnt' present + * Requests to get the [Guild] this ban was removed from, or `null` if the guild wasn't present * * @throws [RequestException] if anything went wrong during the request. */ diff --git a/core/src/main/kotlin/event/guild/EmojisUpdateEvent.kt b/core/src/main/kotlin/event/guild/EmojisUpdateEvent.kt index 1ec436001722..1df62130f16a 100644 --- a/core/src/main/kotlin/event/guild/EmojisUpdateEvent.kt +++ b/core/src/main/kotlin/event/guild/EmojisUpdateEvent.kt @@ -12,6 +12,13 @@ import dev.kord.core.exception.EntityNotFoundException import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy +/** + * The event dispatched when a guild's emojis have been updated. + * + * The [old][old] [GuildEmoji] set may be `null` unless it has been stored by the cache. + * + * See [Guild Emoji Update](https://discord.com/developers/docs/topics/gateway-events#guild-emojis-update) + */ public class EmojisUpdateEvent( public val guildId: Snowflake, public val emojis: Set, diff --git a/core/src/main/kotlin/event/guild/GuildCreateEvent.kt b/core/src/main/kotlin/event/guild/GuildCreateEvent.kt index 6df23c11ddbd..6a863caef408 100644 --- a/core/src/main/kotlin/event/guild/GuildCreateEvent.kt +++ b/core/src/main/kotlin/event/guild/GuildCreateEvent.kt @@ -4,6 +4,17 @@ import dev.kord.core.Kord import dev.kord.core.entity.Guild import dev.kord.core.event.Event +/** + * The event dispatched in 3 scenarios: + * 1. A user is initially connecting, tp lazily load and back-fill information for all unavailable guilds sent in the Ready + * event. Guilds that are unavailable due to an outage will send a [GuildDeleteEvent] + * 2. When a Guild becomes available again to the client + * 3. When the current user joins a new Guild. + * + * _Scenarios 1 and 3 may be marked unavailable during an outage_ + * + * See [Guild Create](https://discord.com/developers/docs/topics/gateway-events#guild-create) + */ public class GuildCreateEvent( public val guild: Guild, override val shard: Int, diff --git a/core/src/main/kotlin/event/guild/GuildDeleteEvent.kt b/core/src/main/kotlin/event/guild/GuildDeleteEvent.kt index a3a42e9a240f..1b58e34ca229 100644 --- a/core/src/main/kotlin/event/guild/GuildDeleteEvent.kt +++ b/core/src/main/kotlin/event/guild/GuildDeleteEvent.kt @@ -5,6 +5,13 @@ import dev.kord.core.Kord import dev.kord.core.entity.Guild import dev.kord.core.event.Event +/** + * The event dispatched when a guild becomes, or was already, unavailable due to an outage, or when the user leaves/is + * removed from a guild. + * If the [unavailable] field was not set, the user was removed from the guild. + * + * See [Guild Delete](https://discord.com/developers/docs/topics/gateway-events#guild-delete) + */ public class GuildDeleteEvent( public val guildId: Snowflake, public val unavailable: Boolean, diff --git a/core/src/main/kotlin/event/guild/GuildScheduledEventCreateEvent.kt b/core/src/main/kotlin/event/guild/GuildScheduledEventCreateEvent.kt index 947b60ec7941..2e86983d91d6 100644 --- a/core/src/main/kotlin/event/guild/GuildScheduledEventCreateEvent.kt +++ b/core/src/main/kotlin/event/guild/GuildScheduledEventCreateEvent.kt @@ -8,6 +8,8 @@ import dev.kord.core.supplier.EntitySupplyStrategy /** * The event dispatched when a scheduled guild event was created. * + * See [Guild Scheduled Event Create](https://discord.com/developers/docs/topics/gateway-events#guild-scheduled-event-create) + * * @see GuildScheduledEvent * @see GuildScheduledEventEvent */ diff --git a/core/src/main/kotlin/event/guild/GuildScheduledEventDeleteEvent.kt b/core/src/main/kotlin/event/guild/GuildScheduledEventDeleteEvent.kt index 5b468fdb033d..9e9566f06b6b 100644 --- a/core/src/main/kotlin/event/guild/GuildScheduledEventDeleteEvent.kt +++ b/core/src/main/kotlin/event/guild/GuildScheduledEventDeleteEvent.kt @@ -9,6 +9,8 @@ import dev.kord.core.supplier.EntitySupplyStrategy * The event dispatched when a scheduled guild event got deleted. * Use [GuildScheduledEvent.status] to know why the event got deleted. * + * See [Guild Scheduled Event Delete](https://discord.com/developers/docs/topics/gateway-events#guild-scheduled-event-delete) + * * @see GuildScheduledEvent * @see GuildScheduledEvent */ diff --git a/core/src/main/kotlin/event/guild/GuildScheduledEventUpdateEvent.kt b/core/src/main/kotlin/event/guild/GuildScheduledEventUpdateEvent.kt index d2afab9a0fbf..348a360d4e39 100644 --- a/core/src/main/kotlin/event/guild/GuildScheduledEventUpdateEvent.kt +++ b/core/src/main/kotlin/event/guild/GuildScheduledEventUpdateEvent.kt @@ -11,6 +11,8 @@ import dev.kord.core.supplier.EntitySupplyStrategy /** * The event dispatched when a [GuildScheduledEvent] gets updated. * + * See [Guild Schedule Event Update](https://discord.com/developers/docs/topics/gateway-events#guild-scheduled-event-update) + * * @property scheduledEvent the updated event, for the old event use [oldEvent] * @property oldEvent the event that was in the cache before the update * diff --git a/core/src/main/kotlin/event/guild/GuildScheduledEventUserEvent.kt b/core/src/main/kotlin/event/guild/GuildScheduledEventUserEvent.kt index 3c0877030eaa..38a9519f12ee 100644 --- a/core/src/main/kotlin/event/guild/GuildScheduledEventUserEvent.kt +++ b/core/src/main/kotlin/event/guild/GuildScheduledEventUserEvent.kt @@ -1,24 +1,28 @@ package dev.kord.core.event.guild import dev.kord.common.entity.Snowflake +import dev.kord.common.exception.RequestException import dev.kord.core.Kord import dev.kord.core.entity.* import dev.kord.core.event.Event +import dev.kord.core.exception.EntityNotFoundException import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy /** * The event dispatched when a user has [subscribed to][GuildScheduledEventUserAddEvent] or * [unsubscribed from][GuildScheduledEventUserRemoveEvent] a [GuildScheduledEvent]. + * + * See [Guild Scheduled Event](https://discord.com/developers/docs/topics/gateway-events#guild-scheduled-event-user-add) */ public sealed interface GuildScheduledEventUserEvent : Event, Strategizable { /** - * The ID of the scheduled guild event + * The ID of the scheduled guild event. */ public val scheduledEventId: Snowflake /** - * The ID of the user that (un)subscribed from the event + * The ID of the user that (un)subscribed from the event. */ public val userId: Snowflake @@ -42,20 +46,63 @@ public sealed interface GuildScheduledEventUserEvent : Event, Strategizable { */ public suspend fun getUserOrNull(): User? = supplier.getUserOrNull(userId) + + /** + * Requests to get the [Member] that (un)subscribed to the event. + * + * @throws [RequestException] if anything went wrong during the request + * @throws [EntityNotFoundException] if the member was not present + */ public suspend fun getMember(): Member = supplier.getMember(guildId, userId) + + /** + * Requests to get the [Member] that (un)subscribed to the event, or `null` if the member was not present. + * + * @throws [RequestException] if anything went wrong during the request + */ public suspend fun getMemberOrNull(): Member? = supplier.getMemberOrNull(guildId, userId) + + /** + * Requests to get the [Guild] that triggered the event. + * + * @throws [RequestException] if anything went wrong during the request + * @throws [EntityNotFoundException] if the guild was not present + */ public suspend fun getGuild(): Guild = supplier.getGuild(guildId) + + /** + * Requests to get the [Guild] that triggered the event, or `null` if the guild was not present. + * + * @throws [RequestException] if anything went wrong during the request + */ public suspend fun getGuildOrNull(): Guild? = supplier.getGuildOrNull(guildId) + + /** + * Requests to get the [GuildScheduledEvent] that triggered the event. + * + * @throws [RequestException] if anything went wrong during the request + * @throws [EntityNotFoundException] if the event was not present + */ public suspend fun getEvent(): GuildScheduledEvent = supplier.getGuildScheduledEvent(guildId, scheduledEventId) + + /** + * Requests to get the [GuildScheduledEvent] that triggered the event, or `null` if the event was not present + * + * @throws [RequestException] if anything went wrong during the request + */ public suspend fun getEventOrNull(): GuildScheduledEvent? = supplier.getGuildScheduledEventOrNull(guildId, scheduledEventId) override fun withStrategy(strategy: EntitySupplyStrategy<*>): GuildScheduledEventUserEvent } -/** The event dispatched when a user has subscribed to a [GuildScheduledEvent]. */ +/** + * The event dispatched when a user has subscribed to a [GuildScheduledEvent]. + * + * See [Guild Scheduled Event User Add](https://discord.com/developers/docs/topics/gateway-events#guild-scheduled-event-user-add) + */ public data class GuildScheduledEventUserAddEvent( override val scheduledEventId: Snowflake, override val userId: Snowflake, @@ -69,7 +116,11 @@ public data class GuildScheduledEventUserAddEvent( GuildScheduledEventUserAddEvent(scheduledEventId, userId, guildId, kord, shard, customContext, strategy.supply(kord)) } -/** The event dispatched when a user has unsubscribed from a [GuildScheduledEvent]. */ +/** + * The event dispatched when a user has unsubscribed from a [GuildScheduledEvent]. + * + * See [Guild Scheduled Event User Remove](https://discord.com/developers/docs/topics/gateway-events#guild-scheduled-event-user-remove) + */ public data class GuildScheduledEventUserRemoveEvent( override val scheduledEventId: Snowflake, override val userId: Snowflake, diff --git a/core/src/main/kotlin/event/guild/GuildUpdateEvent.kt b/core/src/main/kotlin/event/guild/GuildUpdateEvent.kt index bd10aacb484c..3db629568e5a 100644 --- a/core/src/main/kotlin/event/guild/GuildUpdateEvent.kt +++ b/core/src/main/kotlin/event/guild/GuildUpdateEvent.kt @@ -4,6 +4,13 @@ import dev.kord.core.Kord import dev.kord.core.entity.Guild import dev.kord.core.event.Event +/** + * The event dispatched when a [Guild] is updated. + * + * The [old][old] [Guild] may be `null` unless the guild has been stored in the cache. + * + * See [Guild Update](https://discord.com/developers/docs/topics/gateway-events#guild-update) + */ public class GuildUpdateEvent( public val guild: Guild, public val old: Guild?, diff --git a/core/src/main/kotlin/event/guild/IntegrationsUpdateEvent.kt b/core/src/main/kotlin/event/guild/IntegrationsUpdateEvent.kt index 802e9d0ac059..53d9c006e41d 100644 --- a/core/src/main/kotlin/event/guild/IntegrationsUpdateEvent.kt +++ b/core/src/main/kotlin/event/guild/IntegrationsUpdateEvent.kt @@ -1,14 +1,21 @@ package dev.kord.core.event.guild import dev.kord.common.entity.Snowflake +import dev.kord.common.exception.RequestException import dev.kord.core.Kord import dev.kord.core.behavior.GuildBehavior import dev.kord.core.entity.Guild import dev.kord.core.entity.Strategizable import dev.kord.core.event.Event +import dev.kord.core.exception.EntityNotFoundException import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy +/** + * The event dispatched when the integrations for a guild are updated. + * + * See [Guild Interactions Update](https://discord.com/developers/docs/topics/gateway-events#guild-integrations-update) + */ public class IntegrationsUpdateEvent( public val guildId: Snowflake, override val kord: Kord, @@ -16,11 +23,24 @@ public class IntegrationsUpdateEvent( override val customContext: Any?, override val supplier: EntitySupplier = kord.defaultSupplier, ) : Event, Strategizable { - + /** + * The [Guild] that triggered the event. + */ public val guild: GuildBehavior get() = GuildBehavior(guildId, kord) + /** + * Requests to get the [Guild] that triggered the event. + * + * @throws [RequestException] if anything went wrong during the request + * @throws [EntityNotFoundException] if the guild was not present + */ public suspend fun getGuild(): Guild = supplier.getGuild(guildId) + /** + * Requests to get the [Guild] that triggered the event, or `null` if the guild was not present. + * + * @throws [RequestException] if anything went wrong during the request + */ public suspend fun getGuildOrNull(): Guild? = supplier.getGuildOrNull(guildId) override fun withStrategy(strategy: EntitySupplyStrategy<*>): IntegrationsUpdateEvent = diff --git a/core/src/main/kotlin/event/guild/InviteCreateEvent.kt b/core/src/main/kotlin/event/guild/InviteCreateEvent.kt index 055a4665edbb..384859ec9fc2 100644 --- a/core/src/main/kotlin/event/guild/InviteCreateEvent.kt +++ b/core/src/main/kotlin/event/guild/InviteCreateEvent.kt @@ -20,7 +20,9 @@ import kotlinx.datetime.Instant import kotlin.time.Duration /** - * Sent when a new invite to a channel is created. + * The event dispatched when a new invite to a channel is created. + * + * See [Invite Create](https://discord.com/developers/docs/topics/gateway-events#invite-create) */ public class InviteCreateEvent( public val data: InviteCreateData, @@ -131,13 +133,13 @@ public class InviteCreateEvent( * Requests to get the [Channel] this invite is for. * * @throws [RequestException] if anything went wrong during the request. - * @throws [EntityNotFoundException] if the wasn't present. + * @throws [EntityNotFoundException] if the wasn't present. */ public suspend fun getChannel(): Channel = supplier.getChannel(channelId) /** * Requests to get the [Channel] this invite is for, - * returns null if the channel isn't present. + * returns `null` if the channel isn't present. * * @throws [RequestException] if anything went wrong during the request. */ @@ -145,7 +147,7 @@ public class InviteCreateEvent( /** * Requests to get the [Guild] of the invite. - * returns null if the guild isn't present, or if invite does not target a guild. + * returns `null` if the guild isn't present, or if invite does not target a guild. * * @throws [RequestException] if anything went wrong during the request. */ @@ -153,7 +155,7 @@ public class InviteCreateEvent( /** * Requests to get the [User] that created the invite, - * returns null if the user isn't present or no inviter created this invite. + * returns `null` if the user isn't present or no inviter created this invite. * * @throws [RequestException] if anything went wrong during the request. */ @@ -161,7 +163,7 @@ public class InviteCreateEvent( /** * Requests to get the [User] that created the invite as a [Member] of the [Guild][getGuildOrNull], - * returns null if the user isn't present, the invite did not target a guild, or no inviter created the event. + * returns `null` if the user isn't present, the invite did not target a guild, or no inviter created the event. * * @throws [RequestException] if anything went wrong during the request. */ @@ -171,7 +173,7 @@ public class InviteCreateEvent( /** * Requests to get the target [User] of this invite, - * returns null if the user isn't present or the invite did not target a user. + * returns `null` if the user isn't present or the invite did not target a user. * * @throws [RequestException] if anything went wrong during the request. */ @@ -179,7 +181,7 @@ public class InviteCreateEvent( /** * Requests to get the target [User] of this invite as a [Member] of the [Guild][getGuildOrNull], - * returns null if the user isn't present, the invite did not target a guild, or the invite did not target a user. + * returns `null` if the user isn't present, the invite did not target a guild, or the invite did not target a user. * * @throws [RequestException] if anything went wrong during the request. */ diff --git a/core/src/main/kotlin/event/guild/InviteDeleteEvent.kt b/core/src/main/kotlin/event/guild/InviteDeleteEvent.kt index 811ed52a4bbc..108d99002fbb 100644 --- a/core/src/main/kotlin/event/guild/InviteDeleteEvent.kt +++ b/core/src/main/kotlin/event/guild/InviteDeleteEvent.kt @@ -15,7 +15,9 @@ import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy /** - * Sent when an invite is deleted. + * The event dispatched when an invite is deleted. + * + * See [Invite Delete](https://discord.com/developers/docs/topics/gateway-events#invite-delete) */ public class InviteDeleteEvent( public val data: InviteDeleteData, @@ -60,7 +62,7 @@ public class InviteDeleteEvent( /** * Requests to get the [Channel] this invite is for, - * returns null if the channel isn't present. + * returns `null` if the channel isn't present. * * @throws [RequestException] if anything went wrong during the request. */ @@ -68,7 +70,7 @@ public class InviteDeleteEvent( /** * Requests to get the [Guild] of the invite. - * returns null if the guild isn't present, or if invite does not target a guild. + * returns `null` if the guild isn't present, or if invite does not target a guild. * * @throws [RequestException] if anything went wrong during the request. */ diff --git a/core/src/main/kotlin/event/guild/MemberJoinEvent.kt b/core/src/main/kotlin/event/guild/MemberJoinEvent.kt index 0e4029f0293f..9bfd501e9ac8 100644 --- a/core/src/main/kotlin/event/guild/MemberJoinEvent.kt +++ b/core/src/main/kotlin/event/guild/MemberJoinEvent.kt @@ -1,15 +1,22 @@ package dev.kord.core.event.guild import dev.kord.common.entity.Snowflake +import dev.kord.common.exception.RequestException import dev.kord.core.Kord import dev.kord.core.behavior.GuildBehavior import dev.kord.core.entity.Guild import dev.kord.core.entity.Member import dev.kord.core.entity.Strategizable import dev.kord.core.event.Event +import dev.kord.core.exception.EntityNotFoundException import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy +/** + * The event dispatched when a new user joins a guild. + * + * See [Guild Member Add](https://discord.com/developers/docs/topics/gateway-events#guild-member-add) + */ public class MemberJoinEvent( public val member: Member, override val shard: Int, @@ -19,12 +26,29 @@ public class MemberJoinEvent( override val kord: Kord get() = member.kord + /** + * The ID of the guild that triggered this event. + */ public val guildId: Snowflake get() = member.guildId + /** + * The [Guild] that triggered this event. + */ public val guild: GuildBehavior get() = member.guild + /** + * Requests to get the [Guild] that triggered the event. + * + * @throws [RequestException] if anything went wrong during the request + * @throws [EntityNotFoundException] if the guild was not present + */ public suspend fun getGuild(): Guild = supplier.getGuild(guildId) + /** + * Requests to get the [Guild] that triggered the event, or `null` if the guild was not present + * + * @throws [RequestException] if anything went wrong during the request + */ public suspend fun getGuildOrNull(): Guild? = supplier.getGuildOrNull(guildId) override fun withStrategy(strategy: EntitySupplyStrategy<*>): MemberJoinEvent = diff --git a/core/src/main/kotlin/event/guild/MemberLeaveEvent.kt b/core/src/main/kotlin/event/guild/MemberLeaveEvent.kt index e201cd44ad8c..73db30c53fcb 100644 --- a/core/src/main/kotlin/event/guild/MemberLeaveEvent.kt +++ b/core/src/main/kotlin/event/guild/MemberLeaveEvent.kt @@ -1,13 +1,22 @@ package dev.kord.core.event.guild import dev.kord.common.entity.Snowflake +import dev.kord.common.exception.RequestException import dev.kord.core.Kord import dev.kord.core.behavior.GuildBehavior import dev.kord.core.entity.Guild import dev.kord.core.entity.Member import dev.kord.core.entity.User import dev.kord.core.event.Event - +import dev.kord.core.exception.EntityNotFoundException + +/** + * The event dispatched when a user is removed from a guild, via either leave, kick or ban. + * + * The [old][old] [Member] may be `null` unless it has been stored in the cache. + * + * See [Guild Member Remove](https://discord.com/developers/docs/topics/gateway-events#guild-member-remove) + */ public class MemberLeaveEvent( public val user: User, public val old: Member?, @@ -18,10 +27,24 @@ public class MemberLeaveEvent( override val kord: Kord get() = user.kord + /** + * The [Guild] that triggered this event. + */ public val guild: GuildBehavior get() = GuildBehavior(guildId, kord) + /** + * Requests to get the [Guild] that triggered the event. + * + * @throws [RequestException] if anything went wrong during the request + * @throws [EntityNotFoundException] if the guild was not present + */ public suspend fun getGuild(): Guild = guild.asGuild() + /** + * Requests to get the [Guild] that triggered the event, or `null` if the guild was not present + * + * @throws [RequestException] if anything went wrong during the request + */ public suspend fun getGuildOrNull(): Guild? = guild.asGuildOrNull() override fun toString(): String { diff --git a/core/src/main/kotlin/event/guild/MemberUpdateEvent.kt b/core/src/main/kotlin/event/guild/MemberUpdateEvent.kt index 306e393eafb9..ec72dc693de0 100644 --- a/core/src/main/kotlin/event/guild/MemberUpdateEvent.kt +++ b/core/src/main/kotlin/event/guild/MemberUpdateEvent.kt @@ -1,15 +1,24 @@ package dev.kord.core.event.guild import dev.kord.common.entity.Snowflake +import dev.kord.common.exception.RequestException import dev.kord.core.Kord import dev.kord.core.behavior.GuildBehavior import dev.kord.core.entity.Guild import dev.kord.core.entity.Member import dev.kord.core.entity.Strategizable import dev.kord.core.event.Event +import dev.kord.core.exception.EntityNotFoundException import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy +/** + * The event dispatched when a guild member is updated. This event is also dispatched when the user object of a guild member changes. + * + * The [old][old] [Member] may be `null`, unless it has been stored in the cache. + * + * See [Guild Member Update](https://discord.com/developers/docs/topics/gateway-events#guild-member-update) + */ public class MemberUpdateEvent( public val member: Member, public val old: Member?, @@ -18,13 +27,29 @@ public class MemberUpdateEvent( override val customContext: Any?, override val supplier: EntitySupplier = kord.defaultSupplier, ) : Event, Strategizable { - + /** + * The ID of the guild that triggered this event. + */ public val guildId: Snowflake get() = member.guildId + /** + * The [Guild] that triggered this event. + */ public val guild: GuildBehavior get() = member.guild + /** + * Requests to get the [Guild] that triggered the event. + * + * @throws [RequestException] if anything went wrong during the request + * @throws [EntityNotFoundException] if the guild was not present + */ public suspend fun getGuild(): Guild = supplier.getGuild(guildId) + /** + * Requests to get the [Guild] that triggered the event, or `null` if the guild was not present + * + * @throws [RequestException] if anything went wrong during the request + */ public suspend fun getGuildOrNull(): Guild? = supplier.getGuildOrNull(guildId) override fun withStrategy(strategy: EntitySupplyStrategy<*>): MemberUpdateEvent = diff --git a/core/src/main/kotlin/event/guild/MembersChunkEvent.kt b/core/src/main/kotlin/event/guild/MembersChunkEvent.kt index ba4a38aaa8f3..a6f78086b30b 100644 --- a/core/src/main/kotlin/event/guild/MembersChunkEvent.kt +++ b/core/src/main/kotlin/event/guild/MembersChunkEvent.kt @@ -2,6 +2,7 @@ package dev.kord.core.event.guild import dev.kord.common.entity.Snowflake import dev.kord.common.entity.optional.orEmpty +import dev.kord.common.exception.RequestException import dev.kord.core.Kord import dev.kord.core.behavior.GuildBehavior import dev.kord.core.cache.data.MembersChunkData @@ -10,9 +11,16 @@ import dev.kord.core.entity.Member import dev.kord.core.entity.Presence import dev.kord.core.entity.Strategizable import dev.kord.core.event.Event +import dev.kord.core.exception.EntityNotFoundException import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy +/** + * The event dispatched in response to [Guild Request Members](https://discord.com/developers/docs/topics/gateway-events#request-guild-members). + * Using [chunkIndex] and [chunkCount] you cna calculate how many chunks are left for your request. + * + * See [Guild Members Chunk](https://discord.com/developers/docs/topics/gateway-events#guild-members-chunk) + */ public class MembersChunkEvent( public val data: MembersChunkData, override val kord: Kord, @@ -20,28 +28,62 @@ public class MembersChunkEvent( override val customContext: Any?, override val supplier: EntitySupplier = kord.defaultSupplier, ) : Event, Strategizable { - + /** + * The ID of the guild that triggered this event. + */ public val guildId: Snowflake get() = data.guildId + /** + * The [Guild] that triggered this event + */ public val guild: GuildBehavior get() = GuildBehavior(guildId, kord) + /** + * A [Set] of guild [Member]s. + */ public val members: Set get() = data.members.zip(data.users) .map { (member, user) -> Member(member, user, kord) } .toSet() + /** + * The index of the expected chunks for the response. (0 <= [chunkIndex] < [chunkCount]) + */ public val chunkIndex: Int get() = data.chunkIndex + /** + * The total number of expected chunks for this response + */ public val chunkCount: Int get() = data.chunkCount + /** + * A [Set] of IDs for users not found in this guild. + */ public val invalidIds: Set get() = data.notFound.orEmpty() + /** + * A [List] of [Presence]s for the guild [Member]s. + */ public val presences: List get() = data.presences.orEmpty().map { Presence(it, kord) } + /** + * The nonce used for the Guild Members request. + */ public val nonce: String? get() = data.nonce.value + /** + * Requests to get the [Guild] that triggered the event. + * + * @throws [RequestException] if anything went wrong during the request + * @throws [EntityNotFoundException] if the guild was not present + */ public suspend fun getGuild(): Guild = supplier.getGuild(guildId) + /** + * Requests to get the [Guild] that triggered the event, or `null` if the guild was not present + * + * @throws [RequestException] if anything went wrong during the request + */ public suspend fun getGuildOrNull(): Guild? = supplier.getGuildOrNull(guildId) override fun withStrategy(strategy: EntitySupplyStrategy<*>): MembersChunkEvent = diff --git a/core/src/main/kotlin/event/guild/VoiceServerUpdateEvent.kt b/core/src/main/kotlin/event/guild/VoiceServerUpdateEvent.kt index 62d90f402dfd..b58fbb93db02 100644 --- a/core/src/main/kotlin/event/guild/VoiceServerUpdateEvent.kt +++ b/core/src/main/kotlin/event/guild/VoiceServerUpdateEvent.kt @@ -1,14 +1,22 @@ package dev.kord.core.event.guild import dev.kord.common.entity.Snowflake +import dev.kord.common.exception.RequestException import dev.kord.core.Kord import dev.kord.core.behavior.GuildBehavior import dev.kord.core.entity.Guild import dev.kord.core.entity.Strategizable import dev.kord.core.event.Event +import dev.kord.core.exception.EntityNotFoundException import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy +/** + * The event dispatched when a guild's voice server is updated. It is dispatched when initially connecting to voice, + * and when the current voice instance falls over into a new server. + * + * See [Voice Server Update](https://discord.com/developers/docs/topics/gateway-events#voice-server-update) + */ public class VoiceServerUpdateEvent( public val token: String, public val guildId: Snowflake, @@ -18,11 +26,24 @@ public class VoiceServerUpdateEvent( override val customContext: Any?, override val supplier: EntitySupplier = kord.defaultSupplier, ) : Event, Strategizable { - + /** + * The [Guild] that triggered this event. + */ public val guild: GuildBehavior get() = GuildBehavior(guildId, kord) + /** + * Requests to get the [Guild] that triggered the event. + * + * @throws [RequestException] if anything went wrong during the request + * @throws [EntityNotFoundException] if the guild was not present + */ public suspend fun getGuild(): Guild = supplier.getGuild(guildId) + /** + * Requests to get the [Guild] that triggered the event, or `null` if the guild was not present + * + * @throws [RequestException] if anything went wrong during the request + */ public suspend fun getGuildOrNull(): Guild? = supplier.getGuildOrNull(guildId) override fun withStrategy(strategy: EntitySupplyStrategy<*>): VoiceServerUpdateEvent = diff --git a/core/src/main/kotlin/event/guild/WebhookUpdateEvent.kt b/core/src/main/kotlin/event/guild/WebhookUpdateEvent.kt index d23bc9f7b268..077d99339e4c 100644 --- a/core/src/main/kotlin/event/guild/WebhookUpdateEvent.kt +++ b/core/src/main/kotlin/event/guild/WebhookUpdateEvent.kt @@ -1,6 +1,7 @@ package dev.kord.core.event.guild import dev.kord.common.entity.Snowflake +import dev.kord.common.exception.RequestException import dev.kord.core.Kord import dev.kord.core.behavior.GuildBehavior import dev.kord.core.behavior.channel.TopGuildMessageChannelBehavior @@ -8,11 +9,17 @@ import dev.kord.core.entity.Guild import dev.kord.core.entity.Strategizable import dev.kord.core.entity.channel.TopGuildMessageChannel import dev.kord.core.event.Event +import dev.kord.core.exception.EntityNotFoundException import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy import dev.kord.core.supplier.getChannelOf import dev.kord.core.supplier.getChannelOfOrNull +/** + * The event dispatched when a guild channel's webhook is created, update, or deleted. + * + * See [Webhooks update](https://discord.com/developers/docs/topics/gateway-events#webhooks-update) + */ public class WebhookUpdateEvent( public val guildId: Snowflake, public val channelId: Snowflake, @@ -21,17 +28,44 @@ public class WebhookUpdateEvent( override val customContext: Any?, override val supplier: EntitySupplier = kord.defaultSupplier, ) : Event, Strategizable { - + /** + * The [channel][TopGuildMessageChannel] that triggered this event. + */ public val channel: TopGuildMessageChannelBehavior get() = TopGuildMessageChannelBehavior(guildId, channelId, kord) + /** + * The [Guild] that triggered this event. + */ public val guild: GuildBehavior get() = GuildBehavior(guildId, kord) + /** + * Requests to get the [TopGuildMessageChannel] that triggered the event. + * + * @throws [RequestException] if anything went wrong during the request + * @throws [EntityNotFoundException] if the channel was not present + */ public suspend fun getChannel(): TopGuildMessageChannel = supplier.getChannelOf(channelId) + /** + * Requests to get the [TopGuildMessageChannel] that triggered the event, or `null` if the channel was not present + * + * @throws [RequestException] if anything went wrong during the request + */ public suspend fun getChannelOrNull(): TopGuildMessageChannel? = supplier.getChannelOfOrNull(channelId) + /** + * Requests to get the [Guild] that triggered the event. + * + * @throws [RequestException] if anything went wrong during the request + * @throws [EntityNotFoundException] if the guild was not present + */ public suspend fun getGuild(): Guild = guild.asGuild() + /** + * Requests to get the [Guild] that triggered the event, or `null` if the guild was not present + * + * @throws [RequestException] if anything went wrong during the request + */ public suspend fun getGuildOrNull(): Guild? = guild.asGuildOrNull() override fun withStrategy(strategy: EntitySupplyStrategy<*>): WebhookUpdateEvent = From c6a506bd1c40b8094a8172261c4bbe7050a4572d Mon Sep 17 00:00:00 2001 From: NoComment1105 Date: Tue, 6 Dec 2022 15:21:46 +0000 Subject: [PATCH 05/17] I'm going to run out of commit names --- .../interaction/ApplicationCommandCreate.kt | 31 +++++++- .../interaction/ApplicationCommandDelete.kt | 31 +++++++- .../ApplicationCommandInteractionCreate.kt | 24 +++--- ...pplicationCommandPermissionsUpdateEvent.kt | 7 ++ .../interaction/ApplicationCommandUpdate.kt | 30 ++++++- .../AutoCompleteInteractionCreate.kt | 6 +- .../interaction/ComponentInteractionCreate.kt | 18 ++--- .../event/interaction/InteractionCreate.kt | 6 +- .../ModalSubmitInteractionCreate.kt | 6 +- .../event/message/MessageBulkDeleteEvent.kt | 37 ++++++++- .../event/message/MessageCreateEvent.kt | 9 +++ .../event/message/MessageDeleteEvent.kt | 38 ++++++++- .../event/message/MessageUpdateEvent.kt | 26 +++++- .../kotlin/event/message/ReactionAddEvent.kt | 79 ++++++++++++++++++- .../event/message/ReactionRemoveAllEvent.kt | 53 ++++++++++++- .../event/message/ReactionRemoveEmojiEvent.kt | 60 +++++++++++++- .../event/message/ReactionRemoveEvent.kt | 78 +++++++++++++++++- 17 files changed, 489 insertions(+), 50 deletions(-) diff --git a/core/src/main/kotlin/event/interaction/ApplicationCommandCreate.kt b/core/src/main/kotlin/event/interaction/ApplicationCommandCreate.kt index 25464e11c651..807a93d5fba3 100644 --- a/core/src/main/kotlin/event/interaction/ApplicationCommandCreate.kt +++ b/core/src/main/kotlin/event/interaction/ApplicationCommandCreate.kt @@ -4,11 +4,22 @@ import dev.kord.core.Kord import dev.kord.core.entity.application.* import dev.kord.core.event.Event - +/** + * The event dispatched when an Application command is created. + * + * See [Application command create](https://discord.com/developers/docs/interactions/application-commands#create-global-application-command) + * + * @property command The [GuildApplicationCommand] being created + */ public sealed interface ApplicationCommandCreateEvent : Event { public val command: GuildApplicationCommand } +/** + * The event dispatched when a Chat Input command is created. + * + * @see ApplicationCommandCreateEvent + */ public class ChatInputCommandCreateEvent( override val command: GuildChatInputCommand, override val kord: Kord, @@ -16,7 +27,11 @@ public class ChatInputCommandCreateEvent( override val customContext: Any?, ) : ApplicationCommandCreateEvent - +/** + * The event dispatched when a User command is created. + * + * @see ApplicationCommandCreateEvent + */ public class UserCommandCreateEvent( override val command: GuildUserCommand, override val kord: Kord, @@ -24,7 +39,11 @@ public class UserCommandCreateEvent( override val customContext: Any?, ) : ApplicationCommandCreateEvent - +/** + * The event dispatched when a Message command is created. + * + * @see ApplicationCommandCreateEvent + */ public class MessageCommandCreateEvent( override val command: GuildMessageCommand, override val kord: Kord, @@ -32,7 +51,11 @@ public class MessageCommandCreateEvent( override val customContext: Any?, ) : ApplicationCommandCreateEvent - +/** + * The event dispatched when an Unknown application command is created. + * + * @see ApplicationCommandCreateEvent + */ public class UnknownApplicationCommandCreateEvent( override val command: UnknownGuildApplicationCommand, override val kord: Kord, diff --git a/core/src/main/kotlin/event/interaction/ApplicationCommandDelete.kt b/core/src/main/kotlin/event/interaction/ApplicationCommandDelete.kt index 4dce92114a4f..51d72ae18fba 100644 --- a/core/src/main/kotlin/event/interaction/ApplicationCommandDelete.kt +++ b/core/src/main/kotlin/event/interaction/ApplicationCommandDelete.kt @@ -4,11 +4,22 @@ import dev.kord.core.Kord import dev.kord.core.entity.application.* import dev.kord.core.event.Event - +/** + * The event dispatched when an Application command is deleted. + * + * See [Application command create](https://discord.com/developers/docs/interactions/application-commands#create-global-application-command) + * + * @property command The [GuildApplicationCommand] being deleted + */ public sealed interface ApplicationCommandDeleteEvent : Event { public val command: GuildApplicationCommand } +/** + * The event dispatched when a chat input command is deleted. + * + * @see ApplicationCommandDeleteEvent + */ public class ChatInputCommandDeleteEvent( override val command: GuildChatInputCommand, override val kord: Kord, @@ -16,7 +27,11 @@ public class ChatInputCommandDeleteEvent( override val customContext: Any?, ) : ApplicationCommandDeleteEvent - +/** + * The event dispatched when a user command is deleted. + * + * @see ApplicationCommandDeleteEvent + */ public class UserCommandDeleteEvent( override val command: GuildUserCommand, override val kord: Kord, @@ -24,7 +39,11 @@ public class UserCommandDeleteEvent( override val customContext: Any?, ) : ApplicationCommandDeleteEvent - +/** + * The event dispatched when a message command is deleted. + * + * @see ApplicationCommandDeleteEvent + */ public class MessageCommandDeleteEvent( override val command: GuildMessageCommand, override val kord: Kord, @@ -32,7 +51,11 @@ public class MessageCommandDeleteEvent( override val customContext: Any?, ) : ApplicationCommandDeleteEvent - +/** + * The event dispatched when an unknown application command is deleted. + * + * @see ApplicationCommandDeleteEvent + */ public class UnknownApplicationCommandDeleteEvent( override val command: UnknownGuildApplicationCommand, override val kord: Kord, diff --git a/core/src/main/kotlin/event/interaction/ApplicationCommandInteractionCreate.kt b/core/src/main/kotlin/event/interaction/ApplicationCommandInteractionCreate.kt index 731e6e4f7871..38e807a552a3 100644 --- a/core/src/main/kotlin/event/interaction/ApplicationCommandInteractionCreate.kt +++ b/core/src/main/kotlin/event/interaction/ApplicationCommandInteractionCreate.kt @@ -4,31 +4,31 @@ import dev.kord.core.Kord import dev.kord.core.entity.interaction.* import dev.kord.core.event.Event -/** An [Event] that fires when an [ApplicationCommandInteraction] is created. */ +/** The [Event] dispatched when an [ApplicationCommandInteraction] is created. */ public sealed interface ApplicationCommandInteractionCreateEvent : ActionInteractionCreateEvent { override val interaction: ApplicationCommandInteraction } -/** An [Event] that fires when a [GlobalApplicationCommandInteraction] is created. */ +/** The [Event] dispatched when a [GlobalApplicationCommandInteraction] is created. */ public sealed interface GlobalApplicationCommandInteractionCreateEvent : ApplicationCommandInteractionCreateEvent { override val interaction: GlobalApplicationCommandInteraction } -/** An [Event] that fires when a [GuildApplicationCommandInteraction] is created. */ +/** The [Event] dispatched when a [GuildApplicationCommandInteraction] is created. */ public sealed interface GuildApplicationCommandInteractionCreateEvent : ApplicationCommandInteractionCreateEvent { override val interaction: GuildApplicationCommandInteraction } -/** An [Event] that fires when a [UserCommandInteraction] is created. */ +/** The [Event] dispatched when a [UserCommandInteraction] is created. */ public sealed interface UserCommandInteractionCreateEvent : ApplicationCommandInteractionCreateEvent { override val interaction: UserCommandInteraction } -/** An [Event] that fires when a [GuildUserCommandInteraction] is created. */ +/** The [Event] dispatched when a [GuildUserCommandInteraction] is created. */ public class GuildUserCommandInteractionCreateEvent( override val interaction: GuildUserCommandInteraction, override val kord: Kord, @@ -36,7 +36,7 @@ public class GuildUserCommandInteractionCreateEvent( override val customContext: Any?, ) : GuildApplicationCommandInteractionCreateEvent, UserCommandInteractionCreateEvent -/** An [Event] that fires when a [GlobalUserCommandInteraction] is created. */ +/** The [Event] dispatched when a [GlobalUserCommandInteraction] is created. */ public class GlobalUserCommandInteractionCreateEvent( override val interaction: GlobalUserCommandInteraction, override val kord: Kord, @@ -45,12 +45,12 @@ public class GlobalUserCommandInteractionCreateEvent( ) : GlobalApplicationCommandInteractionCreateEvent, UserCommandInteractionCreateEvent -/** An [Event] that fires when a [MessageCommandInteraction] is created. */ +/** The [Event] dispatched when a [MessageCommandInteraction] is created. */ public sealed interface MessageCommandInteractionCreateEvent : ApplicationCommandInteractionCreateEvent { override val interaction: MessageCommandInteraction } -/** An [Event] that fires when a [GuildMessageCommandInteraction] is created. */ +/** The [Event] dispatched when a [GuildMessageCommandInteraction] is created. */ public class GuildMessageCommandInteractionCreateEvent( override val interaction: GuildMessageCommandInteraction, override val kord: Kord, @@ -58,7 +58,7 @@ public class GuildMessageCommandInteractionCreateEvent( override val customContext: Any?, ) : GuildApplicationCommandInteractionCreateEvent, MessageCommandInteractionCreateEvent -/** An [Event] that fires when a [GlobalMessageCommandInteraction] is created. */ +/** The [Event] dispatched when a [GlobalMessageCommandInteraction] is created. */ public class GlobalMessageCommandInteractionCreateEvent( override val interaction: GlobalMessageCommandInteraction, override val kord: Kord, @@ -67,12 +67,12 @@ public class GlobalMessageCommandInteractionCreateEvent( ) : GlobalApplicationCommandInteractionCreateEvent, MessageCommandInteractionCreateEvent -/** An [Event] that fires when a [ChatInputCommandInteraction] is created. */ +/** The [Event] dispatched when a [ChatInputCommandInteraction] is created. */ public sealed interface ChatInputCommandInteractionCreateEvent : ApplicationCommandInteractionCreateEvent { override val interaction: ChatInputCommandInteraction } -/** An [Event] that fires when a [GuildChatInputCommandInteraction] is created. */ +/** The [Event] dispatched when a [GuildChatInputCommandInteraction] is created. */ public class GuildChatInputCommandInteractionCreateEvent( override val interaction: GuildChatInputCommandInteraction, override val kord: Kord, @@ -80,7 +80,7 @@ public class GuildChatInputCommandInteractionCreateEvent( override val customContext: Any?, ) : GuildApplicationCommandInteractionCreateEvent, ChatInputCommandInteractionCreateEvent -/** An [Event] that fires when a [GlobalChatInputCommandInteraction] is created. */ +/** The [Event] dispatched when a [GlobalChatInputCommandInteraction] is created. */ public class GlobalChatInputCommandInteractionCreateEvent( override val interaction: GlobalChatInputCommandInteraction, override val kord: Kord, diff --git a/core/src/main/kotlin/event/interaction/ApplicationCommandPermissionsUpdateEvent.kt b/core/src/main/kotlin/event/interaction/ApplicationCommandPermissionsUpdateEvent.kt index b07e754bfc48..800c70d9d082 100644 --- a/core/src/main/kotlin/event/interaction/ApplicationCommandPermissionsUpdateEvent.kt +++ b/core/src/main/kotlin/event/interaction/ApplicationCommandPermissionsUpdateEvent.kt @@ -4,6 +4,13 @@ import dev.kord.core.Kord import dev.kord.core.entity.application.ApplicationCommandPermissions import dev.kord.core.event.Event +/** + * The event dispatched when an [ApplicationCommandPermissions] are updated. + * + * See [application command permissions update](https://discord.com/developers/docs/interactions/application-commands#edit-application-command-permissions) + * + * @param permissions The [ApplicationCommandPermissions] for the command + */ public class ApplicationCommandPermissionsUpdateEvent( public val permissions: ApplicationCommandPermissions, override val kord: Kord, diff --git a/core/src/main/kotlin/event/interaction/ApplicationCommandUpdate.kt b/core/src/main/kotlin/event/interaction/ApplicationCommandUpdate.kt index 33383e7fd995..05b9634a8914 100644 --- a/core/src/main/kotlin/event/interaction/ApplicationCommandUpdate.kt +++ b/core/src/main/kotlin/event/interaction/ApplicationCommandUpdate.kt @@ -4,11 +4,22 @@ import dev.kord.core.Kord import dev.kord.core.entity.application.* import dev.kord.core.event.Event - +/** + * The event dispatched when an [GuildApplicationCommand] is updated. + * + * See [application command update](https://discord.com/developers/docs/interactions/application-commands#edit-guild-application-command) + * + * @property command The command that was updated + */ public sealed interface ApplicationCommandUpdateEvent : Event { public val command: GuildApplicationCommand } +/** + * The event dispatched when a [GuildChatInputCommand] is updated + * + * @see ApplicationCommandUpdateEvent + */ public class ChatInputCommandUpdateEvent( override val command: GuildChatInputCommand, override val kord: Kord, @@ -16,7 +27,11 @@ public class ChatInputCommandUpdateEvent( override val customContext: Any?, ) : ApplicationCommandUpdateEvent - +/** + * The event dispatched when a [GuildUserCommand] is updated + * + * @see ApplicationCommandUpdateEvent + */ public class UserCommandUpdateEvent( override val command: GuildUserCommand, override val kord: Kord, @@ -24,7 +39,11 @@ public class UserCommandUpdateEvent( override val customContext: Any?, ) : ApplicationCommandUpdateEvent - +/** + * The event dispatched when a [GuildMessageCommand] is updated + * + * @see ApplicationCommandUpdateEvent + */ public class MessageCommandUpdateEvent( override val command: GuildMessageCommand, override val kord: Kord, @@ -32,6 +51,11 @@ public class MessageCommandUpdateEvent( override val customContext: Any?, ) : ApplicationCommandUpdateEvent +/** + * The event dispatched when an [UnknownGuildApplicationCommand] is updated + * + * @see ApplicationCommandUpdateEvent + */ public class UnknownApplicationCommandUpdateEvent( override val command: UnknownGuildApplicationCommand, override val kord: Kord, diff --git a/core/src/main/kotlin/event/interaction/AutoCompleteInteractionCreate.kt b/core/src/main/kotlin/event/interaction/AutoCompleteInteractionCreate.kt index d6d74ee1605e..f6bfc0be47ab 100644 --- a/core/src/main/kotlin/event/interaction/AutoCompleteInteractionCreate.kt +++ b/core/src/main/kotlin/event/interaction/AutoCompleteInteractionCreate.kt @@ -6,12 +6,12 @@ import dev.kord.core.entity.interaction.GlobalAutoCompleteInteraction import dev.kord.core.entity.interaction.GuildAutoCompleteInteraction import dev.kord.core.event.Event -/** An [Event] that fires when an [AutoCompleteInteraction] is created. */ +/** The [Event] dispatched when an [AutoCompleteInteraction] is created. */ public sealed interface AutoCompleteInteractionCreateEvent : DataInteractionCreateEvent { override val interaction: AutoCompleteInteraction } -/** An [Event] that fires when a [GlobalAutoCompleteInteraction] is created. */ +/** The [Event] dispatched when a [GlobalAutoCompleteInteraction] is created. */ public class GlobalAutoCompleteInteractionCreateEvent( override val kord: Kord, override val shard: Int, @@ -19,7 +19,7 @@ public class GlobalAutoCompleteInteractionCreateEvent( override val customContext: Any?, ) : AutoCompleteInteractionCreateEvent -/** An [Event] that fires when a [GuildAutoCompleteInteraction] is created. */ +/** The [Event] dispatched when a [GuildAutoCompleteInteraction] is created. */ public class GuildAutoCompleteInteractionCreateEvent( override val kord: Kord, override val shard: Int, diff --git a/core/src/main/kotlin/event/interaction/ComponentInteractionCreate.kt b/core/src/main/kotlin/event/interaction/ComponentInteractionCreate.kt index 455d7a558d0e..d755aaed6d49 100644 --- a/core/src/main/kotlin/event/interaction/ComponentInteractionCreate.kt +++ b/core/src/main/kotlin/event/interaction/ComponentInteractionCreate.kt @@ -4,32 +4,32 @@ import dev.kord.core.Kord import dev.kord.core.entity.interaction.* import dev.kord.core.event.Event -/** An [Event] that fires when a [ComponentInteraction] is created. */ +/** The [Event] dispatched when a [ComponentInteraction] is created. */ public sealed interface ComponentInteractionCreateEvent : ActionInteractionCreateEvent { override val interaction: ComponentInteraction } -/** An [Event] that fires when a [GlobalComponentInteraction] is created. */ +/** The [Event] dispatched when a [GlobalComponentInteraction] is created. */ public sealed interface GlobalComponentInteractionCreateEvent : ComponentInteractionCreateEvent { override val interaction: GlobalComponentInteraction } -/** An [Event] that fires when a [GuildComponentInteraction] is created. */ +/** The [Event] dispatched when a [GuildComponentInteraction] is created. */ public sealed interface GuildComponentInteractionCreateEvent : ComponentInteractionCreateEvent { override val interaction: GuildComponentInteraction } -/** An [Event] that fires when a [ButtonInteraction] is created. */ +/** The [Event] dispatched when a [ButtonInteraction] is created. */ public sealed interface ButtonInteractionCreateEvent : ComponentInteractionCreateEvent { override val interaction: ButtonInteraction } -/** An [Event] that fires when a [SelectMenuInteraction] is created. */ +/** The [Event] dispatched when a [SelectMenuInteraction] is created. */ public sealed interface SelectMenuInteractionCreateEvent : ComponentInteractionCreateEvent { override val interaction: SelectMenuInteraction } -/** An [Event] that fires when a [GuildButtonInteraction] is created. */ +/** The [Event] dispatched when a [GuildButtonInteraction] is created. */ public class GuildButtonInteractionCreateEvent( override val interaction: GuildButtonInteraction, override val kord: Kord, @@ -37,7 +37,7 @@ public class GuildButtonInteractionCreateEvent( override val customContext: Any?, ) : ButtonInteractionCreateEvent, GuildComponentInteractionCreateEvent -/** An [Event] that fires when a [GlobalButtonInteraction] is created. */ +/** The [Event] dispatched when a [GlobalButtonInteraction] is created. */ public class GlobalButtonInteractionCreateEvent( override val interaction: GlobalButtonInteraction, override val kord: Kord, @@ -45,7 +45,7 @@ public class GlobalButtonInteractionCreateEvent( override val customContext: Any?, ) : ButtonInteractionCreateEvent, GlobalComponentInteractionCreateEvent -/** An [Event] that fires when a [GuildSelectMenuInteraction] is created. */ +/** The [Event] dispatched when a [GuildSelectMenuInteraction] is created. */ public class GuildSelectMenuInteractionCreateEvent( override val interaction: GuildSelectMenuInteraction, override val kord: Kord, @@ -53,7 +53,7 @@ public class GuildSelectMenuInteractionCreateEvent( override val customContext: Any?, ) : SelectMenuInteractionCreateEvent, GuildComponentInteractionCreateEvent -/** An [Event] that fires when a [GlobalSelectMenuInteraction] is created. */ +/** The [Event] dispatched when a [GlobalSelectMenuInteraction] is created. */ public class GlobalSelectMenuInteractionCreateEvent( override val interaction: GlobalSelectMenuInteraction, override val kord: Kord, diff --git a/core/src/main/kotlin/event/interaction/InteractionCreate.kt b/core/src/main/kotlin/event/interaction/InteractionCreate.kt index 53fc045b757f..2ef378b84886 100644 --- a/core/src/main/kotlin/event/interaction/InteractionCreate.kt +++ b/core/src/main/kotlin/event/interaction/InteractionCreate.kt @@ -7,7 +7,7 @@ import dev.kord.core.entity.interaction.Interaction import dev.kord.core.event.Event /** - * An [Event] that fires when an [Interaction] is created. + * The [Event] dispatched when an [Interaction] is created. * * The event should be responded to within 3 seconds. See the methods and extensions of each [Interaction] type for * ways to respond to the particular interaction. @@ -19,12 +19,12 @@ public sealed interface InteractionCreateEvent : Event { public val interaction: Interaction } -/** An [Event] that fires when an [ActionInteraction] is created. */ +/** The [Event] dispatched when an [ActionInteraction] is created. */ public sealed interface ActionInteractionCreateEvent : InteractionCreateEvent { override val interaction: ActionInteraction } -/** An [Event] that fires when a [DataInteraction] is created. */ +/** The [Event] dispatched when a [DataInteraction] is created. */ public sealed interface DataInteractionCreateEvent : InteractionCreateEvent { override val interaction: DataInteraction } diff --git a/core/src/main/kotlin/event/interaction/ModalSubmitInteractionCreate.kt b/core/src/main/kotlin/event/interaction/ModalSubmitInteractionCreate.kt index 0ad7ac76ad23..050a4a6d3a3e 100644 --- a/core/src/main/kotlin/event/interaction/ModalSubmitInteractionCreate.kt +++ b/core/src/main/kotlin/event/interaction/ModalSubmitInteractionCreate.kt @@ -6,12 +6,12 @@ import dev.kord.core.entity.interaction.GuildModalSubmitInteraction import dev.kord.core.entity.interaction.ModalSubmitInteraction import dev.kord.core.event.Event -/** An [Event] that fires when a [ModalSubmitInteraction] is created. */ +/** The [Event] dispatched when a [ModalSubmitInteraction] is created. */ public sealed interface ModalSubmitInteractionCreateEvent : ActionInteractionCreateEvent { override val interaction: ModalSubmitInteraction } -/** An [Event] that fires when a [GuildModalSubmitInteraction] is created. */ +/** The [Event] dispatched when a [GuildModalSubmitInteraction] is created. */ public class GuildModalSubmitInteractionCreateEvent( override val interaction: GuildModalSubmitInteraction, override val kord: Kord, @@ -19,7 +19,7 @@ public class GuildModalSubmitInteractionCreateEvent( override val customContext: Any?, ) : ModalSubmitInteractionCreateEvent -/** An [Event] that fires when a [GlobalModalSubmitInteraction] is created. */ +/** The [Event] dispatched when a [GlobalModalSubmitInteraction] is created. */ public class GlobalModalSubmitInteractionCreateEvent( override val interaction: GlobalModalSubmitInteraction, override val shard: Int, diff --git a/core/src/main/kotlin/event/message/MessageBulkDeleteEvent.kt b/core/src/main/kotlin/event/message/MessageBulkDeleteEvent.kt index 1e5cf4cadab3..a47f30b35c96 100644 --- a/core/src/main/kotlin/event/message/MessageBulkDeleteEvent.kt +++ b/core/src/main/kotlin/event/message/MessageBulkDeleteEvent.kt @@ -1,6 +1,7 @@ package dev.kord.core.event.message import dev.kord.common.entity.Snowflake +import dev.kord.common.exception.RequestException import dev.kord.core.Kord import dev.kord.core.behavior.GuildBehavior import dev.kord.core.behavior.channel.MessageChannelBehavior @@ -9,11 +10,22 @@ import dev.kord.core.entity.Message import dev.kord.core.entity.Strategizable import dev.kord.core.entity.channel.MessageChannel import dev.kord.core.event.Event +import dev.kord.core.exception.EntityNotFoundException import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy import dev.kord.core.supplier.getChannelOf import dev.kord.core.supplier.getChannelOfOrNull +/** + * The event dispatched when messages are deleted in bulk from a channel. + * + * See [Message bulk delete event](https://discord.com/developers/docs/resources/channel#bulk-delete-messages) + * + * @param messageIds The [Set] of message Ids to delete + * @param messages The [Set] of messages to delete as [Message]s + * @param channelId The channel to delete them from. + * @param guildId The guild the event occurred in + */ public class MessageBulkDeleteEvent( public val messageIds: Set, public val messages: Set, @@ -24,15 +36,38 @@ public class MessageBulkDeleteEvent( override val customContext: Any?, override val supplier: EntitySupplier = kord.defaultSupplier, ) : Event, Strategizable { - + /** + * The [MessageChannelBehavior] of the channel that triggered this event. + */ public val channel: MessageChannelBehavior get() = MessageChannelBehavior(channelId, kord) + /** + * The [GuildBehavior] that triggered this event + */ public val guild: GuildBehavior? get() = guildId?.let { GuildBehavior(it, kord) } + /** + * Requests to get the channel triggering the event as a [MessageChannel] + * + * @throws [RequestException] if anything went wrong during the request. + * @throws [EntityNotFoundException] if the [MessageChannel] wasn't present. + */ public suspend fun getChannel(): MessageChannel = supplier.getChannelOf(channelId) + /** + * Requests to get the channel triggering the event as a [MessageChannel]. + * Returns `null` if the channel is not present + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getChannelOrNull(): MessageChannel? = supplier.getChannelOfOrNull(channelId) + /** + * Requests to get the channel triggering the event. + * Returns `null` if the guild is not present + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getGuild(): Guild? = guildId?.let { supplier.getGuildOrNull(it) } override fun withStrategy(strategy: EntitySupplyStrategy<*>): MessageBulkDeleteEvent = diff --git a/core/src/main/kotlin/event/message/MessageCreateEvent.kt b/core/src/main/kotlin/event/message/MessageCreateEvent.kt index 67d944d6574d..89af7b75fe46 100644 --- a/core/src/main/kotlin/event/message/MessageCreateEvent.kt +++ b/core/src/main/kotlin/event/message/MessageCreateEvent.kt @@ -12,6 +12,15 @@ import dev.kord.core.event.Event import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy +/** + * The event dispatched when a [Message] is created. + * + * See [Message create event](https://discord.com/developers/docs/resources/channel#create-message) + * + * @param message The [Message] that triggered the event + * @param guildId The guild ID the event occurred in. It may be `null` if the id was not stored in the cache + * @param member The member that was triggered in the event. It may be `null` if the member was not stored in the cache + */ public class MessageCreateEvent( public val message: Message, public val guildId: Snowflake?, diff --git a/core/src/main/kotlin/event/message/MessageDeleteEvent.kt b/core/src/main/kotlin/event/message/MessageDeleteEvent.kt index d9db077f3c24..4a79d4147374 100644 --- a/core/src/main/kotlin/event/message/MessageDeleteEvent.kt +++ b/core/src/main/kotlin/event/message/MessageDeleteEvent.kt @@ -1,19 +1,32 @@ package dev.kord.core.event.message import dev.kord.common.entity.Snowflake +import dev.kord.common.exception.RequestException import dev.kord.core.Kord import dev.kord.core.behavior.GuildBehavior import dev.kord.core.behavior.channel.MessageChannelBehavior import dev.kord.core.entity.Guild import dev.kord.core.entity.Message import dev.kord.core.entity.Strategizable +import dev.kord.core.entity.channel.DmChannel import dev.kord.core.entity.channel.MessageChannel import dev.kord.core.event.Event +import dev.kord.core.exception.EntityNotFoundException import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy import dev.kord.core.supplier.getChannelOf import dev.kord.core.supplier.getChannelOfOrNull +/** + * The event dispatched when a message is deleted. + * + * See [Message delete](https://discord.com/developers/docs/resources/channel#delete-message) + * + * @param messageId The ID of the message that triggered the event + * @param channelId The ID of the channel that triggered the event + * @param guildId The Id of the guild that triggered the event. It may be `null` if the message was not stored in the cache + * @param message The message that triggered the event. It may be `null` if the message was not stored in the cache + */ public class MessageDeleteEvent( public val messageId: Snowflake, public val channelId: Snowflake, @@ -24,15 +37,38 @@ public class MessageDeleteEvent( override val customContext: Any?, override val supplier: EntitySupplier = kord.defaultSupplier, ) : Event, Strategizable { - + /** + * The [MessageChannelBehavior] that triggered the event. + */ public val channel: MessageChannelBehavior get() = MessageChannelBehavior(channelId, kord) + /** + * The [GuildBehavior] that triggered the event + */ public val guild: GuildBehavior? get() = guildId?.let { GuildBehavior(it, kord) } + /** + * Requests to get the channel triggering the event as a [MessageChannel] + * + * @throws [RequestException] if anything went wrong during the request. + * @throws [EntityNotFoundException] if the [MessageChannel] wasn't present. + */ public suspend fun getChannel(): MessageChannel = supplier.getChannelOf(channelId) + /** + * Requests to get the channel this message was delete from, if it was deleted in one, + * returns `null` if the [MessageChannel] isn't present. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getChannelOrNull(): MessageChannel? = supplier.getChannelOfOrNull(channelId) + /** + * Requests to get the guild this message was created in, if it was created in one, + * returns null if the [Guild] isn't present or the message was a [DM][DmChannel]. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getGuild(): Guild? = guildId?.let { supplier.getGuildOrNull(it) } override fun withStrategy(strategy: EntitySupplyStrategy<*>): MessageDeleteEvent = diff --git a/core/src/main/kotlin/event/message/MessageUpdateEvent.kt b/core/src/main/kotlin/event/message/MessageUpdateEvent.kt index a6a90138e858..520775830920 100644 --- a/core/src/main/kotlin/event/message/MessageUpdateEvent.kt +++ b/core/src/main/kotlin/event/message/MessageUpdateEvent.kt @@ -2,15 +2,28 @@ package dev.kord.core.event.message import dev.kord.common.entity.DiscordPartialMessage import dev.kord.common.entity.Snowflake +import dev.kord.common.exception.RequestException import dev.kord.core.Kord import dev.kord.core.behavior.MessageBehavior import dev.kord.core.behavior.channel.MessageChannelBehavior import dev.kord.core.entity.Message import dev.kord.core.entity.Strategizable +import dev.kord.core.entity.channel.MessageChannel import dev.kord.core.event.Event +import dev.kord.core.exception.EntityNotFoundException import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy +/** + * The event dispatched when a message is updated. + * + * See [Message update event](https://discord.com/developers/docs/resources/channel#edit-message) + * + * @param messageId The ID of the message that triggered the event + * @param channelId The ID of the channel that the event occurred in + * @param new The new message + * @param old The old [Message]. May be `null` if the old message was not stored in the cache + */ public class MessageUpdateEvent( public val messageId: Snowflake, public val channelId: Snowflake, @@ -32,9 +45,20 @@ public class MessageUpdateEvent( */ public val channel: MessageChannelBehavior get() = MessageChannelBehavior(id = channelId, kord = kord) - + /** + * Requests to get the message triggering the event as a [Message] + * + * @throws [RequestException] if anything went wrong during the request. + * @throws [EntityNotFoundException] if the [Message] wasn't present. + */ public suspend fun getMessage(): Message = supplier.getMessage(channelId = channelId, messageId = messageId) + /** + * Requests to get the message triggering the event as a [Message]. + * Returns `null` if the [Message] wasn't present. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getMessageOrNull(): Message? = supplier.getMessageOrNull(channelId = channelId, messageId = messageId) override fun withStrategy(strategy: EntitySupplyStrategy<*>): MessageUpdateEvent = diff --git a/core/src/main/kotlin/event/message/ReactionAddEvent.kt b/core/src/main/kotlin/event/message/ReactionAddEvent.kt index 748ee835cfda..baff0630aadc 100644 --- a/core/src/main/kotlin/event/message/ReactionAddEvent.kt +++ b/core/src/main/kotlin/event/message/ReactionAddEvent.kt @@ -1,6 +1,7 @@ package dev.kord.core.event.message import dev.kord.common.entity.Snowflake +import dev.kord.common.exception.RequestException import dev.kord.core.Kord import dev.kord.core.behavior.GuildBehavior import dev.kord.core.behavior.MemberBehavior @@ -10,11 +11,23 @@ import dev.kord.core.behavior.channel.MessageChannelBehavior import dev.kord.core.entity.* import dev.kord.core.entity.channel.MessageChannel import dev.kord.core.event.Event +import dev.kord.core.exception.EntityNotFoundException import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy import dev.kord.core.supplier.getChannelOf import dev.kord.core.supplier.getChannelOfOrNull +/** + * The event triggered when a reaction is added to a message. + * + * See [Reaction Add event](https://discord.com/developers/docs/topics/gateway-events#message-reaction-add) + * + * @param userId The ID of the user that added the reaction + * @param channelId The ID of the channel the reaction was added in + * @param messageId The ID of the message the event happen on + * @param guildId The ID of the guild the event occurred on. It may be `null` if it was not stored in the cache + * @param emoji The [ReactionEmoji] added to the [message] + */ public class ReactionAddEvent( public val userId: Snowflake, public val channelId: Snowflake, @@ -26,29 +39,93 @@ public class ReactionAddEvent( override val customContext: Any?, override val supplier: EntitySupplier = kord.defaultSupplier, ) : Event, Strategizable { - + /** + * The [MessageChannelBehavior] that triggered the event + */ public val channel: MessageChannelBehavior get() = MessageChannelBehavior(channelId, kord) + /** + * The [GuildBehavior] that triggered the event + */ public val guild: GuildBehavior? get() = guildId?.let { GuildBehavior(it, kord) } + /** + * The [MessageBehavior] that triggered the event + */ public val message: MessageBehavior get() = MessageBehavior(channelId, messageId, kord) + /** + * The [UserBehavior] that triggered the event + */ public val user: UserBehavior get() = UserBehavior(userId, kord) + /** + * The user as a [MemberBehavior] that triggered the event + */ public val userAsMember: MemberBehavior? get() = guildId?.let { MemberBehavior(it, userId, kord) } + /** + * Requests to get the channel triggering the event as a [MessageChannel] + * + * @throws [RequestException] if anything went wrong during the request. + * @throws [EntityNotFoundException] if the [MessageChannel] wasn't present. + */ public suspend fun getChannel(): MessageChannel = supplier.getChannelOf(channelId) + /** + * Requests to get the channel triggering the event as a [MessageChannel]. + * Returns `null` if the [MessageChannel] wasn't present. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getChannelOrNull(): MessageChannel? = supplier.getChannelOfOrNull(channelId) + /** + * Requests to get the guild triggering the event as a [Guild]. + * Returns `null` if the [Guild] wasn't present. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getGuild(): Guild? = guildId?.let { supplier.getGuildOrNull(it) } + /** + * Requests to get the message triggering the event as a [Message] + * + * @throws [RequestException] if anything went wrong during the request. + * @throws [EntityNotFoundException] if the [Message] wasn't present. + */ public suspend fun getMessage(): Message = supplier.getMessage(channelId = channelId, messageId = messageId) + + /** + * Requests to get the message triggering the event as a [Message]. + * Returns `null` if the [Message] wasn't present. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getMessageOrNull(): Message? = supplier.getMessageOrNull(channelId = channelId, messageId = messageId) + /** + * Requests to get the user triggering the event as a [User] + * + * @throws [RequestException] if anything went wrong during the request. + * @throws [EntityNotFoundException] if the [User] wasn't present. + */ public suspend fun getUser(): User = supplier.getUser(userId) + + /** + * Requests to get the user triggering the event as a [User] + * Returns `null` if the [User] wasn't present. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getUserOrNull(): User? = supplier.getUserOrNull(userId) + /** + * Requests to get the user triggering the event as a [Member] + * + * @throws [RequestException] if anything went wrong during the request. + * @throws [EntityNotFoundException] if the [Member] wasn't present. + */ public suspend fun getUserAsMember(): Member? = guildId?.let { supplier.getMemberOrNull(it, userId) } override fun withStrategy(strategy: EntitySupplyStrategy<*>): ReactionAddEvent = diff --git a/core/src/main/kotlin/event/message/ReactionRemoveAllEvent.kt b/core/src/main/kotlin/event/message/ReactionRemoveAllEvent.kt index 3641526b07df..a63b3ad042e5 100644 --- a/core/src/main/kotlin/event/message/ReactionRemoveAllEvent.kt +++ b/core/src/main/kotlin/event/message/ReactionRemoveAllEvent.kt @@ -1,6 +1,7 @@ package dev.kord.core.event.message import dev.kord.common.entity.Snowflake +import dev.kord.common.exception.RequestException import dev.kord.core.Kord import dev.kord.core.behavior.GuildBehavior import dev.kord.core.behavior.MessageBehavior @@ -10,11 +11,21 @@ import dev.kord.core.entity.Message import dev.kord.core.entity.Strategizable import dev.kord.core.entity.channel.MessageChannel import dev.kord.core.event.Event +import dev.kord.core.exception.EntityNotFoundException import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy import dev.kord.core.supplier.getChannelOf import dev.kord.core.supplier.getChannelOfOrNull +/** + * The event dispatched when all the reactions are removed from a message + * + * See [Reaction remove all](https://discord.com/developers/docs/topics/gateway-events#message-reaction-remove-all) + * + * @param channelId The ID of the channel that triggered the event + * @param messageId The ID of the message that triggered the event + * @param guildId The ID of the guild that triggered the event, or `null` if it was not stored in the cache + */ public class ReactionRemoveAllEvent( public val channelId: Snowflake, public val messageId: Snowflake, @@ -24,19 +35,59 @@ public class ReactionRemoveAllEvent( override val customContext: Any?, override val supplier: EntitySupplier = kord.defaultSupplier, ) : Event, Strategizable { - + /** + * The [MessageChannelBehavior] that triggered the event + */ public val channel: MessageChannelBehavior get() = MessageChannelBehavior(channelId, kord) + /** + * The [GuildBehavior] that triggered the event + */ public val guild: GuildBehavior? get() = guildId?.let { GuildBehavior(it, kord) } + /** + * The [MessageBehavior] that triggered the event + */ public val message: MessageBehavior get() = MessageBehavior(channelId, messageId, kord) + /** + * Requests to get the channel triggering the event as a [MessageChannel] + * + * @throws [RequestException] if anything went wrong during the request. + * @throws [EntityNotFoundException] if the [MessageChannel] wasn't present. + */ public suspend fun getChannel(): MessageChannel = supplier.getChannelOf(channelId) + + /** + * Requests to get the channel triggering the event as a [MessageChannel]. + * Returns `null` if the [MessageChannel] wasn't present. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getChannelOrNull(): MessageChannel? = supplier.getChannelOfOrNull(channelId) + /** + * Requests to get the guild triggering the event as a [Guild]. + * Returns `null` if the [Guild] wasn't present. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getGuild(): Guild? = guildId?.let { supplier.getGuildOrNull(it) } + /** + * Requests to get the message triggering the event as a [Message] + * + * @throws [RequestException] if anything went wrong during the request. + * @throws [EntityNotFoundException] if the [Message] wasn't present. + */ public suspend fun getMessage(): Message = supplier.getMessage(channelId = channelId, messageId = messageId) + + /** + * Requests to get the message triggering the event as a [Message]. + * Returns `null` if the [Message] wasn't present. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getMessageOrNull(): Message? = supplier.getMessageOrNull(channelId = channelId, messageId = messageId) override fun withStrategy(strategy: EntitySupplyStrategy<*>): ReactionRemoveAllEvent = diff --git a/core/src/main/kotlin/event/message/ReactionRemoveEmojiEvent.kt b/core/src/main/kotlin/event/message/ReactionRemoveEmojiEvent.kt index 9397b45fa6b9..10d441871076 100644 --- a/core/src/main/kotlin/event/message/ReactionRemoveEmojiEvent.kt +++ b/core/src/main/kotlin/event/message/ReactionRemoveEmojiEvent.kt @@ -1,6 +1,7 @@ package dev.kord.core.event.message import dev.kord.common.entity.Snowflake +import dev.kord.common.exception.RequestException import dev.kord.core.Kord import dev.kord.core.behavior.GuildBehavior import dev.kord.core.behavior.MessageBehavior @@ -12,11 +13,19 @@ import dev.kord.core.entity.ReactionEmoji import dev.kord.core.entity.Strategizable import dev.kord.core.entity.channel.TopGuildMessageChannel import dev.kord.core.event.Event +import dev.kord.core.exception.EntityNotFoundException import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy import dev.kord.core.supplier.getChannelOf import dev.kord.core.supplier.getChannelOfOrNull +/** + * The event triggered when all instances reaction are removed. + * + * See [Reaction remove event](https://discord.com/developers/docs/topics/gateway-events#message-reaction-remove-emoji) + * + * @param data The data from the event + */ public class ReactionRemoveEmojiEvent( public val data: ReactionRemoveEmojiData, override val kord: Kord, @@ -30,6 +39,9 @@ public class ReactionRemoveEmojiEvent( */ public val channelId: Snowflake get() = data.channelId + /** + * The [GuildMessageChannelBehavior] that triggered the event. + */ public val channel: GuildMessageChannelBehavior get() = GuildMessageChannelBehavior( guildId = guildId, @@ -38,34 +50,76 @@ public class ReactionRemoveEmojiEvent( ) /** - * The id of the [Guild]. + * The ID of the [Guild] that triggered the event. */ public val guildId: Snowflake get() = data.guildId + /** + * The [GuildBehavior] that triggered the event. + */ public val guild: GuildBehavior get() = GuildBehavior(id = guildId, kord = kord) /** - * The id of the message. + * The ID of the message that triggered the event. */ public val messageId: Snowflake get() = data.messageId + /** + * The [MessageBehavior] that triggered the event. + */ public val message: MessageBehavior get() = MessageBehavior(channelId = channelId, messageId = messageId, kord = kord) /** - * The emoji that was removed. + * The emoji that was removed in the event. */ public val emoji: ReactionEmoji get() = ReactionEmoji.from(data.emoji) + /** + * Requests to get the channel triggering the event as a [TopGuildMessageChannel] + * + * @throws [RequestException] if anything went wrong during the request. + * @throws [EntityNotFoundException] if the [TopGuildMessageChannel] wasn't present. + */ public suspend fun getChannel(): TopGuildMessageChannel = supplier.getChannelOf(channelId) + /** + * Requests to get the channel triggering the event as a [TopGuildMessageChannel]. + * Returns `null` if the [TopGuildMessageChannel] wasn't present. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getChannelOrNull(): TopGuildMessageChannel? = supplier.getChannelOfOrNull(channelId) + /** + * Requests to get the guild triggering the event as a [Guild] + * + * @throws [RequestException] if anything went wrong during the request. + * @throws [EntityNotFoundException] if the [Guild] wasn't present. + */ public suspend fun getGuild(): Guild = supplier.getGuild(guildId) + /** + * Requests to get the guild triggering the event as a [Guild]. + * Returns `null` if the [Guild] wasn't present. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getGuildOrNull(): Guild? = supplier.getGuildOrNull(guildId) + /** + * Requests to get the message triggering the event as a [Message] + * + * @throws [RequestException] if anything went wrong during the request. + * @throws [EntityNotFoundException] if the [Message] wasn't present. + */ public suspend fun getMessage(): Message = supplier.getMessage(channelId = channelId, messageId = messageId) + /** + * Requests to get the message triggering the event as a [Message]. + * Returns `null` if the [Message] wasn't present. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getMessageOrNull(): Message? = supplier.getMessageOrNull(channelId = channelId, messageId = messageId) override fun withStrategy(strategy: EntitySupplyStrategy<*>): ReactionRemoveEmojiEvent = diff --git a/core/src/main/kotlin/event/message/ReactionRemoveEvent.kt b/core/src/main/kotlin/event/message/ReactionRemoveEvent.kt index ab94985e183f..6c90624b1b2f 100644 --- a/core/src/main/kotlin/event/message/ReactionRemoveEvent.kt +++ b/core/src/main/kotlin/event/message/ReactionRemoveEvent.kt @@ -1,6 +1,7 @@ package dev.kord.core.event.message import dev.kord.common.entity.Snowflake +import dev.kord.common.exception.RequestException import dev.kord.core.Kord import dev.kord.core.behavior.GuildBehavior import dev.kord.core.behavior.MemberBehavior @@ -9,12 +10,25 @@ import dev.kord.core.behavior.UserBehavior import dev.kord.core.behavior.channel.MessageChannelBehavior import dev.kord.core.entity.* import dev.kord.core.entity.channel.MessageChannel +import dev.kord.core.entity.channel.TopGuildMessageChannel import dev.kord.core.event.Event +import dev.kord.core.exception.EntityNotFoundException import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy import dev.kord.core.supplier.getChannelOf import dev.kord.core.supplier.getChannelOfOrNull +/** + * The event dispatched when a reaction is removed from a message. + * + * See [Reaction remove event](https://discord.com/developers/docs/topics/gateway-events#message-reaction-remove) + * + * @param userId The ID of the user that triggered the event + * @param channelId THe ID of the channel that triggered the event + * @param messageId The ID of the message that triggered the event + * @param guildId The ID of the guild that triggered the event. It may be `null` if it was not stored in the cache + * @param emoji The emoji removed from the message + */ public class ReactionRemoveEvent( public val userId: Snowflake, public val channelId: Snowflake, @@ -26,31 +40,93 @@ public class ReactionRemoveEvent( override val customContext: Any?, override val supplier: EntitySupplier = kord.defaultSupplier, ) : Event, Strategizable { - + /** + * The [MessageChannelBehavior] that triggered the event + */ public val channel: MessageChannelBehavior get() = MessageChannelBehavior(channelId, kord) + /** + * The [GuildBehavior] that triggered the event + */ public val guild: GuildBehavior? get() = guildId?.let { GuildBehavior(it, kord) } + /** + * The [MessageBehavior] that triggered the event + */ public val message: MessageBehavior get() = MessageBehavior(channelId, messageId, kord) + /** + * The [UserBehavior] that triggered the event + */ public val user: UserBehavior get() = UserBehavior(userId, kord) + /** + * The [MemberBehavior] that triggered the event + */ public val userAsMember: MemberBehavior? get() = guildId?.let { MemberBehavior(it, userId, kord) } + /** + * Requests to get the channel triggering the event as a [MessageChannel] + * + * @throws [RequestException] if anything went wrong during the request. + * @throws [EntityNotFoundException] if the [MessageChannel] wasn't present. + */ public suspend fun getChannel(): MessageChannel = supplier.getChannelOf(channelId) + /** + * Requests to get the channel triggering the event as a [MessageChannel]. + * Returns `null` if the [MessageChannel] wasn't present. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getChannelOrNull(): MessageChannel? = supplier.getChannelOfOrNull(channelId) + /** + * Requests to get the guild triggering the event as a [Guild] + * + * @throws [RequestException] if anything went wrong during the request. + * @throws [EntityNotFoundException] if the [Guild] wasn't present. + */ public suspend fun getGuild(): Guild? = guildId?.let { supplier.getGuildOrNull(it) } + /** + * Requests to get the message triggering the event as a [Message] + * + * @throws [RequestException] if anything went wrong during the request. + * @throws [EntityNotFoundException] if the [Message] wasn't present. + */ public suspend fun getMessage(): Message = supplier.getMessage(channelId = channelId, messageId = messageId) + /** + * Requests to get the message triggering the event as a [Message]. + * Returns `null` if the [Message] wasn't present. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getMessageOrNull(): Message? = supplier.getMessageOrNull(channelId = channelId, messageId = messageId) + /** + * Requests to get the user triggering the event as a [User] + * + * @throws [RequestException] if anything went wrong during the request. + * @throws [EntityNotFoundException] if the [User] wasn't present. + */ public suspend fun getUser(): User = supplier.getUser(userId) + /** + * Requests to get the user triggering the event as a [User]. + * Returns `null` if the [TopGuildMessageChannel] wasn't present. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getUserOrNull(): User? = supplier.getUserOrNull(userId) + /** + * Requests to get the user triggering the event as a [Member]. + * Returns `null` if the [TopGuildMessageChannel] wasn't present. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getUserAsMember(): Member? = guildId?.let { supplier.getMemberOrNull(guildId = guildId, userId = userId) } From 5db1987320df3f0d64a4e6a40ba0f996cbf26434 Mon Sep 17 00:00:00 2001 From: NoComment1105 Date: Mon, 20 Feb 2023 10:38:46 +0000 Subject: [PATCH 06/17] Add docs to new nulllable guild functions --- .../src/main/kotlin/event/channel/ChannelPinsUpdateEvent.kt | 3 --- core/src/main/kotlin/event/channel/TypingStartEvent.kt | 3 --- .../src/main/kotlin/event/message/MessageBulkDeleteEvent.kt | 6 ++++++ core/src/main/kotlin/event/message/MessageDeleteEvent.kt | 6 ++++++ core/src/main/kotlin/event/message/ReactionAddEvent.kt | 6 ++++++ .../src/main/kotlin/event/message/ReactionRemoveAllEvent.kt | 6 ++++++ core/src/main/kotlin/event/message/ReactionRemoveEvent.kt | 6 ++++++ 7 files changed, 30 insertions(+), 6 deletions(-) diff --git a/core/src/main/kotlin/event/channel/ChannelPinsUpdateEvent.kt b/core/src/main/kotlin/event/channel/ChannelPinsUpdateEvent.kt index c6f2cbdcfc77..bad4bbd69193 100644 --- a/core/src/main/kotlin/event/channel/ChannelPinsUpdateEvent.kt +++ b/core/src/main/kotlin/event/channel/ChannelPinsUpdateEvent.kt @@ -73,9 +73,6 @@ public class ChannelPinsUpdateEvent( */ public suspend fun getChannelOrNull(): MessageChannel? = supplier.getChannelOfOrNull(channelId) - /** - * Returns a copy of this class with a new [supplier] provided by the [strategy]. - */ override fun withStrategy(strategy: EntitySupplyStrategy<*>): ChannelPinsUpdateEvent = ChannelPinsUpdateEvent(data, kord, shard, customContext, strategy.supply(kord)) diff --git a/core/src/main/kotlin/event/channel/TypingStartEvent.kt b/core/src/main/kotlin/event/channel/TypingStartEvent.kt index f162aea3f0e3..0f25ef363a37 100644 --- a/core/src/main/kotlin/event/channel/TypingStartEvent.kt +++ b/core/src/main/kotlin/event/channel/TypingStartEvent.kt @@ -122,9 +122,6 @@ public class TypingStartEvent( */ public suspend fun getGuildOrNull(): Guild? = guildId?.let { supplier.getGuildOrNull(it) } - /** - * Returns a copy of this class with a new [supplier] provided by the [strategy]. - */ override fun withStrategy(strategy: EntitySupplyStrategy<*>): TypingStartEvent = TypingStartEvent(data, kord, shard, customContext, strategy.supply(kord)) diff --git a/core/src/main/kotlin/event/message/MessageBulkDeleteEvent.kt b/core/src/main/kotlin/event/message/MessageBulkDeleteEvent.kt index 8558fdd835c5..a1814e5d5310 100644 --- a/core/src/main/kotlin/event/message/MessageBulkDeleteEvent.kt +++ b/core/src/main/kotlin/event/message/MessageBulkDeleteEvent.kt @@ -75,6 +75,12 @@ public class MessageBulkDeleteEvent( ) public suspend fun getGuild(): Guild? = guildId?.let { supplier.getGuildOrNull(it) } + /** + * Requests to get the channel triggering the event. + * Returns `null` if the guild is not present + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getGuildOrNull(): Guild? = guildId?.let { supplier.getGuildOrNull(it) } override fun withStrategy(strategy: EntitySupplyStrategy<*>): MessageBulkDeleteEvent = diff --git a/core/src/main/kotlin/event/message/MessageDeleteEvent.kt b/core/src/main/kotlin/event/message/MessageDeleteEvent.kt index 48c80bb59e0c..cb1d03d92cc4 100644 --- a/core/src/main/kotlin/event/message/MessageDeleteEvent.kt +++ b/core/src/main/kotlin/event/message/MessageDeleteEvent.kt @@ -76,6 +76,12 @@ public class MessageDeleteEvent( ) public suspend fun getGuild(): Guild? = guildId?.let { supplier.getGuildOrNull(it) } + /** + * Requests to get the guild this message was created in, if it was created in one, + * returns null if the [Guild] isn't present or the message was a [DM][DmChannel]. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getGuildOrNull(): Guild? = guildId?.let { supplier.getGuildOrNull(it) } override fun withStrategy(strategy: EntitySupplyStrategy<*>): MessageDeleteEvent = diff --git a/core/src/main/kotlin/event/message/ReactionAddEvent.kt b/core/src/main/kotlin/event/message/ReactionAddEvent.kt index 346198090b9c..9f0d78af072e 100644 --- a/core/src/main/kotlin/event/message/ReactionAddEvent.kt +++ b/core/src/main/kotlin/event/message/ReactionAddEvent.kt @@ -93,6 +93,12 @@ public class ReactionAddEvent( ) public suspend fun getGuild(): Guild? = guildId?.let { supplier.getGuildOrNull(it) } + /** + * Requests to get the guild triggering the event as a [Guild]. + * Returns `null` if the [Guild] wasn't present. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getGuildOrNull(): Guild? = guildId?.let { supplier.getGuildOrNull(it) } /** diff --git a/core/src/main/kotlin/event/message/ReactionRemoveAllEvent.kt b/core/src/main/kotlin/event/message/ReactionRemoveAllEvent.kt index 046137001462..d325afbc4637 100644 --- a/core/src/main/kotlin/event/message/ReactionRemoveAllEvent.kt +++ b/core/src/main/kotlin/event/message/ReactionRemoveAllEvent.kt @@ -79,6 +79,12 @@ public class ReactionRemoveAllEvent( ) public suspend fun getGuild(): Guild? = guildId?.let { supplier.getGuildOrNull(it) } + /** + * Requests to get the guild triggering the event as a [Guild]. + * Returns `null` if the [Guild] wasn't present. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getGuildOrNull(): Guild? = guildId?.let { supplier.getGuildOrNull(it) } /** diff --git a/core/src/main/kotlin/event/message/ReactionRemoveEvent.kt b/core/src/main/kotlin/event/message/ReactionRemoveEvent.kt index 8b064877c0d6..2b018255d72b 100644 --- a/core/src/main/kotlin/event/message/ReactionRemoveEvent.kt +++ b/core/src/main/kotlin/event/message/ReactionRemoveEvent.kt @@ -94,6 +94,12 @@ public class ReactionRemoveEvent( ) public suspend fun getGuild(): Guild? = guildId?.let { supplier.getGuildOrNull(it) } + /** + * Requests to get the guild triggering the event as a [Guild]. + * Returns `null` if the [Guild] wasn't present. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getGuildOrNull(): Guild? = guildId?.let { supplier.getGuildOrNull(it) } /** From 083719c28509fdb3f2ca18d6fc392af5f4539659 Mon Sep 17 00:00:00 2001 From: NoComment1105 Date: Mon, 20 Feb 2023 10:56:59 +0000 Subject: [PATCH 07/17] Document remaining events --- .../event/message/MessageDeleteEvent.kt | 2 +- .../main/kotlin/event/role/RoleCreateEvent.kt | 27 ++++++++++++++++++ .../main/kotlin/event/role/RoleDeleteEvent.kt | 27 +++++++++++++++++- .../main/kotlin/event/role/RoleUpdateEvent.kt | 28 +++++++++++++++++++ .../kotlin/event/user/PresenceUpdateEvent.kt | 11 ++++++++ .../main/kotlin/event/user/UserUpdateEvent.kt | 8 ++++++ .../event/user/VoiceStateUpdateEvent.kt | 8 ++++++ 7 files changed, 109 insertions(+), 2 deletions(-) diff --git a/core/src/main/kotlin/event/message/MessageDeleteEvent.kt b/core/src/main/kotlin/event/message/MessageDeleteEvent.kt index cb1d03d92cc4..eb7240a72bef 100644 --- a/core/src/main/kotlin/event/message/MessageDeleteEvent.kt +++ b/core/src/main/kotlin/event/message/MessageDeleteEvent.kt @@ -24,7 +24,7 @@ import dev.kord.core.supplier.getChannelOfOrNull * * @param messageId The ID of the message that triggered the event * @param channelId The ID of the channel that triggered the event - * @param guildId The Id of the guild that triggered the event. It may be `null` if the message was not stored in the cache + * @param guildId The ID of the guild that triggered the event. It may be `null` if the message was not stored in the cache * @param message The message that triggered the event. It may be `null` if the message was not stored in the cache */ public class MessageDeleteEvent( diff --git a/core/src/main/kotlin/event/role/RoleCreateEvent.kt b/core/src/main/kotlin/event/role/RoleCreateEvent.kt index 62512d1104ca..1fcae3aa7027 100644 --- a/core/src/main/kotlin/event/role/RoleCreateEvent.kt +++ b/core/src/main/kotlin/event/role/RoleCreateEvent.kt @@ -1,15 +1,24 @@ package dev.kord.core.event.role import dev.kord.common.entity.Snowflake +import dev.kord.common.exception.RequestException import dev.kord.core.Kord import dev.kord.core.behavior.GuildBehavior import dev.kord.core.entity.Guild import dev.kord.core.entity.Role import dev.kord.core.entity.Strategizable import dev.kord.core.event.Event +import dev.kord.core.exception.EntityNotFoundException import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy +/** + * The event dispatched when a [Role] is created. + * + * See [Guild Role Create Event](https://discord.com/developers/docs/topics/gateway-events#guild-role-create) + * + * @param role The created [Role] that triggered the event + */ public class RoleCreateEvent( public val role: Role, override val shard: Int, @@ -19,12 +28,30 @@ public class RoleCreateEvent( override val kord: Kord get() = role.kord + /** + * The ID of the guild that triggered the event. + */ public val guildId: Snowflake get() = role.guildId + /** + * The [GuildBehavior] tht triggered the event + */ public val guild: GuildBehavior get() = GuildBehavior(guildId, kord) + /** + * Requests to get the guild triggering the event as a [Guild]. + * + * @throws [RequestException] if anything went wrong during the request. + * @throws [EntityNotFoundException] if the guild is `null` + */ public suspend fun getGuild(): Guild = supplier.getGuild(guildId) + /** + * Requests to get the guild triggering the event as a [Guild]. + * Returns `null` if the [Guild] wasn't present. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getGuildOrNull(): Guild? = supplier.getGuildOrNull(guildId) override fun withStrategy(strategy: EntitySupplyStrategy<*>): RoleCreateEvent = diff --git a/core/src/main/kotlin/event/role/RoleDeleteEvent.kt b/core/src/main/kotlin/event/role/RoleDeleteEvent.kt index 86811766a653..1de200815185 100644 --- a/core/src/main/kotlin/event/role/RoleDeleteEvent.kt +++ b/core/src/main/kotlin/event/role/RoleDeleteEvent.kt @@ -1,15 +1,26 @@ package dev.kord.core.event.role import dev.kord.common.entity.Snowflake +import dev.kord.common.exception.RequestException import dev.kord.core.Kord import dev.kord.core.behavior.GuildBehavior import dev.kord.core.entity.Guild import dev.kord.core.entity.Role import dev.kord.core.entity.Strategizable import dev.kord.core.event.Event +import dev.kord.core.exception.EntityNotFoundException import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy +/** + * The event dispatched when a [Role] is deleted. + * + * See [Guild Role Delete Event](https://discord.com/developers/docs/topics/gateway-events#guild-role-delete) + * + * @param guildId The ID of the guild that triggered the event + * @param roleId The ID of the role that triggered the event + * @param role The [Role] that triggered the event. It may be `null` if it was not stored in the cache + */ public class RoleDeleteEvent( public val guildId: Snowflake, public val roleId: Snowflake, @@ -19,11 +30,25 @@ public class RoleDeleteEvent( override val customContext: Any?, override val supplier: EntitySupplier = kord.defaultSupplier, ) : Event, Strategizable { - + /** + * The [GuildBehavior] that triggered the event. + */ public val guild: GuildBehavior get() = GuildBehavior(guildId, kord) + /** + * Requests to get the guild triggering the event as a [Guild]. + * + * @throws [RequestException] if anything went wrong during the request. + * @throws [EntityNotFoundException] if the guild is `null` + */ public suspend fun getGuild(): Guild = supplier.getGuild(guildId) + /** + * Requests to get the guild triggering the event as a [Guild]. + * Returns `null` if the [Guild] wasn't present. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getGuildOrNull(): Guild? = supplier.getGuildOrNull(guildId) override fun withStrategy(strategy: EntitySupplyStrategy<*>): RoleDeleteEvent = diff --git a/core/src/main/kotlin/event/role/RoleUpdateEvent.kt b/core/src/main/kotlin/event/role/RoleUpdateEvent.kt index 75442611b24e..da04321edf35 100644 --- a/core/src/main/kotlin/event/role/RoleUpdateEvent.kt +++ b/core/src/main/kotlin/event/role/RoleUpdateEvent.kt @@ -1,15 +1,25 @@ package dev.kord.core.event.role import dev.kord.common.entity.Snowflake +import dev.kord.common.exception.RequestException import dev.kord.core.Kord import dev.kord.core.behavior.GuildBehavior import dev.kord.core.entity.Guild import dev.kord.core.entity.Role import dev.kord.core.entity.Strategizable import dev.kord.core.event.Event +import dev.kord.core.exception.EntityNotFoundException import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy +/** + * The event dispatched when a [Role] is updated. + * + * See [Guild Role Update event](https://discord.com/developers/docs/topics/gateway-events#guild-role-update) + * + * @param role The updated [Role] that triggered the event. + * @param old The old [Role] that triggered the event. It may be `null` if it was not stored in the cache + */ public class RoleUpdateEvent( public val role: Role, public val old: Role?, @@ -20,12 +30,30 @@ public class RoleUpdateEvent( override val kord: Kord get() = role.kord + /** + * The ID of the guild that triggered the event. + */ public val guildId: Snowflake get() = role.guildId + /** + * The [GuildBehavior] that triggered the event. + */ public val guild: GuildBehavior get() = GuildBehavior(guildId, kord) + /** + * Requests to get the guild triggering the event as a [Guild]. + * + * @throws [RequestException] if anything went wrong during the request. + * @throws [EntityNotFoundException] if the guild is `null` + */ public suspend fun getGuild(): Guild = supplier.getGuild(guildId) + /** + * Requests to get the guild triggering the event as a [Guild]. + * Returns `null` if the [Guild] wasn't present. + * + * @throws [RequestException] if anything went wrong during the request. + */ public suspend fun getGuildOrNull(): Guild? = supplier.getGuildOrNull(guildId) override fun withStrategy(strategy: EntitySupplyStrategy<*>): RoleUpdateEvent = diff --git a/core/src/main/kotlin/event/user/PresenceUpdateEvent.kt b/core/src/main/kotlin/event/user/PresenceUpdateEvent.kt index 2ed362e9fb25..bdf98359abf6 100644 --- a/core/src/main/kotlin/event/user/PresenceUpdateEvent.kt +++ b/core/src/main/kotlin/event/user/PresenceUpdateEvent.kt @@ -12,6 +12,17 @@ import dev.kord.core.exception.EntityNotFoundException import dev.kord.core.supplier.EntitySupplier import dev.kord.core.supplier.EntitySupplyStrategy +/** + * The event dispatched when a [Presence] is updated. + * + * See [Presence Update](https://discord.com/developers/docs/topics/gateway-events#guild-role-update) + * + * @param oldUser The old [User] that triggered the event. It may be `null` if it was not stored in the cache. + * @param user The [DiscordPresenceUser] that triggered the event. + * @param guildId The ID of the guild the event was triggered from. + * @param old The old [Presence] that triggered the event. It may be `null` if it was not stored in the cache. + * @param presence The new [Presence] that triggered the event. + */ public class PresenceUpdateEvent( public val oldUser: User?, public val user: DiscordPresenceUser, diff --git a/core/src/main/kotlin/event/user/UserUpdateEvent.kt b/core/src/main/kotlin/event/user/UserUpdateEvent.kt index 84245d69d048..d10e471f8a45 100644 --- a/core/src/main/kotlin/event/user/UserUpdateEvent.kt +++ b/core/src/main/kotlin/event/user/UserUpdateEvent.kt @@ -4,6 +4,14 @@ import dev.kord.core.Kord import dev.kord.core.entity.User import dev.kord.core.event.Event +/** + * The event dispatched when a [User] is updated. + * + * See [User update](https://discord.com/developers/docs/topics/gateway-events#user-update) + * + * @param old The old [User] that triggered the event. It may be `null` if it was not stored in the cache + * @param user The [User] that triggered the event. + */ public class UserUpdateEvent( public val old: User?, public val user: User, diff --git a/core/src/main/kotlin/event/user/VoiceStateUpdateEvent.kt b/core/src/main/kotlin/event/user/VoiceStateUpdateEvent.kt index bae274ae00df..b645ebd6ebe2 100644 --- a/core/src/main/kotlin/event/user/VoiceStateUpdateEvent.kt +++ b/core/src/main/kotlin/event/user/VoiceStateUpdateEvent.kt @@ -4,6 +4,14 @@ import dev.kord.core.Kord import dev.kord.core.entity.VoiceState import dev.kord.core.event.Event +/** + * The event dispatched when a [VoiceState] is updated. + * + * See [Voice State update](https://discord.com/developers/docs/topics/gateway-events#voice-state-update) + * + * @param old The old [VoiceState] that triggered the event. It may be `null` if it was not stored in the cache + * @param state The [VoiceState] that triggered the event. + */ public class VoiceStateUpdateEvent( public val old: VoiceState?, public val state: VoiceState, From 943b33b45eb8382214bcbd0a93e297530abb0743 Mon Sep 17 00:00:00 2001 From: NoComment Date: Tue, 21 Feb 2023 17:50:09 +0000 Subject: [PATCH 08/17] Document the outlying files for the core package --- core/src/main/kotlin/ClientResources.kt | 10 + core/src/main/kotlin/Kord.kt | 151 ++++++++++++++- core/src/main/kotlin/Unsafe.kt | 237 +++++++++++++++++++++++- 3 files changed, 385 insertions(+), 13 deletions(-) diff --git a/core/src/main/kotlin/ClientResources.kt b/core/src/main/kotlin/ClientResources.kt index 9a9d9758ac57..a5a5d7aadfbe 100644 --- a/core/src/main/kotlin/ClientResources.kt +++ b/core/src/main/kotlin/ClientResources.kt @@ -6,6 +6,16 @@ import dev.kord.gateway.builder.Shards import io.ktor.client.* import kotlin.DeprecationLevel.ERROR +/** + * The resources for the Kord Instance. + * + * @param token The Bots token + * @param applicationId The ID of the application + * @param shards The [Shards] for the application + * @param maxConcurrency The maximum concurrency for the bot. Can be obtained by calling the `Route.GatewayBotGet` endpoint. + * @param httpClient The [HttpClient] the client is connected through + * @param defaultStrategy The default [EntitySupplyStrategy] for the client. + */ public class ClientResources( public val token: String, public val applicationId: Snowflake, diff --git a/core/src/main/kotlin/Kord.kt b/core/src/main/kotlin/Kord.kt index 536dcbd4ef5e..ccee5abdfe7e 100644 --- a/core/src/main/kotlin/Kord.kt +++ b/core/src/main/kotlin/Kord.kt @@ -57,6 +57,9 @@ public class Kord( private val interceptor: GatewayEventInterceptor, ) : CoroutineScope { + /** + * Returns a [Flow] of Nitro [StickerPack]s + */ public val nitroStickerPacks: Flow get() = defaultSupplier.getNitroStickerPacks() @@ -94,9 +97,15 @@ public class Kord( override val coroutineContext: CoroutineContext = SupervisorJob() + dispatcher + /** + * Returns a [Flow] of [Region]s know to the bot. + */ public val regions: Flow get() = defaultSupplier.regions + /** + * Returns a [Flow] of [Guild]s know to the bot. + */ public val guilds: Flow get() = defaultSupplier.guilds @@ -143,6 +152,12 @@ public class Kord( public fun with(strategy: EntitySupplyStrategy): T = strategy.supply(this) + /** + * Requests to get the information of the current application using the [EntitySupplyStrategy.rest] supplier. + * + * Entities will be fetched from Discord directly, ignoring any cached values. + * @throws RestRequestException when the request failed. + */ public suspend fun getApplicationInfo(): Application = with(EntitySupplyStrategy.rest).getApplicationInfo() /** @@ -355,6 +370,11 @@ public class Kord( ): Invite? = with(EntitySupplyStrategy.rest).getInviteOrNull(code, withCounts, withExpiration, scheduledEventId) + /** + * Gets a [Sticker] from its [id]. + * + * @return [EntityNotFoundException.stickerNotFound] if the sticker is not found + */ public suspend fun getSticker(id: Snowflake): Sticker = defaultSupplier.getSticker(id) @@ -420,11 +440,23 @@ public class Kord( } } - + /** + * Gets the [GlobalApplicationCommand]s for this bot. + * + * @param withLocalizations Whether to get the commands with localisations or not. Defaults to `null` + * @return a [Flow] of [GlobalApplicationCommand]s for this bot. + */ public fun getGlobalApplicationCommands(withLocalizations: Boolean? = null): Flow { return defaultSupplier.getGlobalApplicationCommands(resources.applicationId, withLocalizations) } + /** + * Gets the [GuildApplicationCommand]s for a given [guildId]. + * + * @param guildId The ID of the guild to get the commands for + * @param withLocalizations Whether to get the commands with localizations or not. Defaults to `null` + * @return a [Flow] of [GuildApplicationCommand]s for the given [guildId]. + */ public fun getGuildApplicationCommands( guildId: Snowflake, withLocalizations: Boolean? = null, @@ -432,11 +464,24 @@ public class Kord( return defaultSupplier.getGuildApplicationCommands(resources.applicationId, guildId, withLocalizations) } + /** + * Gets a [GuildApplicationCommand] based on the [guildId] and [commandId]. + * + * @param guildId The ID of the guild to get the command for + * @param commandId The ID of the command to get + * @return The [GuildApplicationCommand] or [EntityNotFoundException.applicationCommandNotFound] if it was not found. + */ public suspend fun getGuildApplicationCommand(guildId: Snowflake, commandId: Snowflake): GuildApplicationCommand { return defaultSupplier.getGuildApplicationCommand(resources.applicationId, guildId, commandId) } - + /** + * Gets a [GuildApplicationCommand] based on the [guildId] and [commandId]. + * + * @param guildId The ID of the guild to get the command from + * @param commandId The ID of the command to get + * @return The [GuildApplicationCommand] or `null` if it was not found. + */ public suspend fun getGuildApplicationCommandOrNull( guildId: Snowflake, commandId: Snowflake @@ -444,7 +489,13 @@ public class Kord( return defaultSupplier.getGuildApplicationCommandOrNull(resources.applicationId, guildId, commandId) } - + /** + * Gets a Guild application command of type [T], based on the [guildId] and [commandId] + * + * @param guildId The ID the guild to get the command from + * @param commandId The ID of the command to get + * @return The command of type [T] or [EntityNotFoundException.applicationCommandNotFound] if it was not found. + */ public suspend inline fun getGuildApplicationCommandOf( guildId: Snowflake, commandId: Snowflake @@ -452,7 +503,13 @@ public class Kord( return defaultSupplier.getGuildApplicationCommandOf(resources.applicationId, guildId, commandId) } - + /** + * Gets a Guild application command of type [T], based on the [guildId] and [commandId] + * + * @param guildId The ID the guild to get the command from + * @param commandId The ID of the command to get + * @return The command of type [T] or `null` if it was not found. + */ public suspend inline fun getGuildApplicationCommandOfOrNull( guildId: Snowflake, commandId: Snowflake @@ -460,27 +517,55 @@ public class Kord( return defaultSupplier.getGuildApplicationCommandOfOrNull(resources.applicationId, guildId, commandId) } - + /** + * Gets a [GlobalApplicationCommand] based off the [commandId]. + * + * @param commandId The ID of the command to get. + * @return The [GlobalApplicationCommand] or [EntityNotFoundException.applicationCommandNotFound] if it was not found. + */ public suspend fun getGlobalApplicationCommand(commandId: Snowflake): GlobalApplicationCommand { return defaultSupplier.getGlobalApplicationCommand(resources.applicationId, commandId) } - + /** + * Gets a [GlobalApplicationCommand] based off the [commandId]. + * + * @param commandId The ID of the command to get. + * @return The [GlobalApplicationCommand] or `null` if it was not found. + */ public suspend fun getGlobalApplicationCommandOrNull(commandId: Snowflake): GlobalApplicationCommand? { return defaultSupplier.getGlobalApplicationCommandOrNull(resources.applicationId, commandId) } - + /** + * Gets a Global application command of type [T] based off the [commandId]. + * + * @param commandId The ID of the command to get. + * @return The application command of type [T] or [EntityNotFoundException.applicationCommandNotFound] if it was not found. + */ public suspend fun getGlobalApplicationCommandOf(commandId: Snowflake): T { return defaultSupplier.getGlobalApplicationCommandOf(resources.applicationId, commandId) } - + /** + * Gets a Global application command of type [T] based off the [commandId]. + * + * @param commandId The ID of the command to get. + * @return The application command of type [T] or `null` if it was not found. + */ public suspend fun getGlobalApplicationCommandOfOrNull(commandId: Snowflake): T? { return defaultSupplier.getGlobalApplicationCommandOfOrNull(resources.applicationId, commandId) } + /** + * Creates a [GlobalChatInputCommand] for this bot. + * + * @param name The command name + * @param description The command description + * @param builder A [GlobalChatInputCreateBuilder] to modify the command. + * @return The [GlobalChatInputCommand] for the bot. + */ public suspend inline fun createGlobalChatInputCommand( name: String, description: String, @@ -497,6 +582,13 @@ public class Kord( return GlobalChatInputCommand(data, rest.interaction) } + /** + * Creates a [GlobalMessageCommand] for this bot. + * + * @param name The command name + * @param builder A [GlobalMessageCommandCreateBuilder] to modify the command. + * @return The [GlobalMessageCommand] for the bot. + */ public suspend inline fun createGlobalMessageCommand( name: String, builder: GlobalMessageCommandCreateBuilder.() -> Unit = {}, @@ -508,6 +600,13 @@ public class Kord( return GlobalMessageCommand(data, rest.interaction) } + /** + * Creates a [GlobalUserCommand] for this bot. + * + * @param name The command name + * @param builder A [GlobalUserCommandCreateBuilder] to modify the command. + * @return The [GlobalUserCommand] for the bot. + */ public suspend inline fun createGlobalUserCommand( name: String, builder: GlobalUserCommandCreateBuilder.() -> Unit = {}, @@ -519,7 +618,12 @@ public class Kord( return GlobalUserCommand(data, rest.interaction) } - + /** + * Creates multiple [GlobalApplicationCommand]s. + * + * @param builder A [GlobalMultiApplicationCommandBuilder] to create the commands in. + * @return A [Flow] of [GlobalApplicationCommand]s for the bot. + */ public suspend inline fun createGlobalApplicationCommands( builder: GlobalMultiApplicationCommandBuilder.() -> Unit, ): Flow { @@ -534,6 +638,14 @@ public class Kord( } } + /** + * Creates a [GuildChatInputCommand] for a given [guildId] + * + * @param guildId The ID of the guild to create the command + * @param name The name of the command + * @param description The description of the command + * @param builder A [ChatInputCreateBuilder] to modify the command + */ public suspend inline fun createGuildChatInputCommand( guildId: Snowflake, name: String, @@ -554,6 +666,13 @@ public class Kord( } + /** + * Creates a [GuildMessageCommand] for a given [guildId] + * + * @param guildId The ID of the guild to create the command + * @param name The name of the command + * @param builder A [MessageCommandCreateBuilder] to modify the command + */ public suspend inline fun createGuildMessageCommand( guildId: Snowflake, name: String, @@ -570,6 +689,13 @@ public class Kord( return GuildMessageCommand(data, rest.interaction) } + /** + * Creates a [GuildUserCommand] for a given [guildId] + * + * @param guildId The ID of the guild to create the command + * @param name The name of the command + * @param builder A [UserCommandCreateBuilder] to modify the command + */ public suspend inline fun createGuildUserCommand( guildId: Snowflake, name: String, @@ -587,7 +713,12 @@ public class Kord( return GuildUserCommand(data, rest.interaction) } - + /** + * Creates multiple [GuildApplicationCommand]s. + * + * @param builder A [GuildMultiApplicationCommandBuilder] to create the commands in. + * @return A [Flow] of [GuildApplicationCommand]s for the bot. + */ public suspend inline fun createGuildApplicationCommands( guildId: Snowflake, builder: GuildMultiApplicationCommandBuilder.() -> Unit, diff --git a/core/src/main/kotlin/Unsafe.kt b/core/src/main/kotlin/Unsafe.kt index 269d0676fb5c..615be4e3921a 100644 --- a/core/src/main/kotlin/Unsafe.kt +++ b/core/src/main/kotlin/Unsafe.kt @@ -26,94 +26,287 @@ import dev.kord.rest.service.InteractionService @KordUnsafe @KordExperimental public class Unsafe(private val kord: Kord) { - + /** + * Returns an [AutoModerationRuleBehavior] for a given [guildId]. + * + * @param guildId The ID to create the [AutoModerationRuleBehavior] for + * @param ruleId The ID of the [AutoModerationRuleBehavior] + * @return The created [AutoModerationRuleBehaviorImpl] + */ public fun autoModerationRule(guildId: Snowflake, ruleId: Snowflake): AutoModerationRuleBehavior = AutoModerationRuleBehaviorImpl(guildId, ruleId, kord) + /** + * Returns an [KeywordAutoModerationRuleBehavior] for a given [guildId]. + * + * @param guildId The ID to create the [KeywordAutoModerationRuleBehavior] for + * @param ruleId The ID of the [KeywordAutoModerationRuleBehavior] + * @return The created [KeywordAutoModerationRuleBehaviorImpl] + */ public fun keywordAutoModerationRule(guildId: Snowflake, ruleId: Snowflake): KeywordAutoModerationRuleBehavior = KeywordAutoModerationRuleBehaviorImpl(guildId, ruleId, kord) + /** + * Returns an [SpamAutoModerationRuleBehavior] for a given [guildId]. + * + * @param guildId The ID to create the [SpamAutoModerationRuleBehavior] for + * @param ruleId The ID of the [SpamAutoModerationRuleBehavior] + * @return The created [SpamAutoModerationRuleBehaviorImpl] + */ public fun spamAutoModerationRule(guildId: Snowflake, ruleId: Snowflake): SpamAutoModerationRuleBehavior = SpamAutoModerationRuleBehaviorImpl(guildId, ruleId, kord) + /** + * Returns an [KeywordPresetAutoModerationRuleBehavior] for a given [guildId]. + * + * @param guildId The ID to create the [KeywordPresetAutoModerationRuleBehavior] for + * @param ruleId The ID of the [KeywordPresetAutoModerationRuleBehavior] + * @return The created [KeywordPresetAutoModerationRuleBehaviorImpl] + */ public fun keywordPresetAutoModerationRule( guildId: Snowflake, ruleId: Snowflake, ): KeywordPresetAutoModerationRuleBehavior = KeywordPresetAutoModerationRuleBehaviorImpl(guildId, ruleId, kord) + /** + * Returns an [MentionSpamAutoModerationRuleBehavior] for a given [guildId]. + * + * @param guildId The ID to create the [MentionSpamAutoModerationRuleBehavior] for + * @param ruleId The ID of the [MentionSpamAutoModerationRuleBehavior] + * @return The created [MentionSpamAutoModerationRuleBehaviorImpl] + */ public fun mentionSpamAutoModerationRule( guildId: Snowflake, ruleId: Snowflake, ): MentionSpamAutoModerationRuleBehavior = MentionSpamAutoModerationRuleBehaviorImpl(guildId, ruleId, kord) + /** + * Returns a [MessageBehavior] for a given [messageId] + * + * @param channelId The ID of the channel the message was sent in + * @param messageId The ID of the message + * @return The [MessageBehavior] for the message + */ public fun message(channelId: Snowflake, messageId: Snowflake): MessageBehavior = MessageBehavior(channelId = channelId, messageId = messageId, kord = kord) + /** + * Returns a [ChannelBehavior] for a given [id] + * + * @param id The ID of the channel + * @return The [ChannelBehavior] for the channel + */ public fun channel(id: Snowflake): ChannelBehavior = ChannelBehavior(id, kord) + /** + * Returns a [MessageChannelBehavior] for a given [id] + * + * @param id The ID of the channel + * @return The [MessageChannelBehavior] for the channel + */ public fun messageChannel(id: Snowflake): MessageChannelBehavior = MessageChannelBehavior(id, kord) + /** + * Returns a [TopGuildChannelBehavior] for a given [id] + * + * @param guildId The ID of the guild the channel is in + * @param id The ID of the channel + * @return The [TopGuildChannelBehavior] for the channel + */ public fun topGuildChannel(guildId: Snowflake, id: Snowflake): TopGuildChannelBehavior = TopGuildChannelBehavior(guildId = guildId, id = id, kord = kord) + /** + * Returns a [CategorizableChannelBehavior] for a given [id] + * + * @param guildId The ID of the guild the channel is in + * @param id The ID of the channel + * @return The [CategorizableChannelBehavior] for the channel + */ public fun categorizableChannel(guildId: Snowflake, id: Snowflake): CategorizableChannelBehavior = CategorizableChannelBehavior(guildId, id, kord) + /** + * Returns a [TopGuildMessageChannelBehavior] for a given [id] + * + * @param guildId The ID of the guild the channel is in + * @param id The ID of the channel + * @return The [TopGuildMessageChannelBehavior] for the channel + */ public fun topGuildMessageChannel(guildId: Snowflake, id: Snowflake): TopGuildMessageChannelBehavior = TopGuildMessageChannelBehavior(guildId = guildId, id = id, kord = kord) + /** + * Returns a [GuildChannelBehavior] for a given [id] + * + * @param guildId The ID of the guild the channel is in + * @param id The ID of the channel + * @return The [GuildChannelBehavior] for the channel + */ public fun guildChannel(guildId: Snowflake, id: Snowflake): GuildChannelBehavior = GuildChannelBehavior(guildId, id, kord) + /** + * Returns a [GuildMessageChannelBehavior] for a given [id] + * + * @param guildId The ID of the guild the channel is in + * @param id The ID of the channel + * @return The [GuildMessageChannelBehavior] for the channel + */ public fun guildMessageChannel(guildId: Snowflake, id: Snowflake): GuildMessageChannelBehavior = GuildMessageChannelBehavior(guildId, id, kord) + /** + * Returns a [NewsChannelBehavior] for a given [id] + * + * @param guildId The ID of the guild the channel is in + * @param id The ID of the channel + * @return The [NewsChannelBehavior] for the channel + */ public fun newsChannel(guildId: Snowflake, id: Snowflake): NewsChannelBehavior = NewsChannelBehavior(guildId = guildId, id = id, kord = kord) + /** + * Returns a [TextChannelBehavior] for a given [id] + * + * @param guildId The ID of the guild the channel is in + * @param id The ID of the channel + * @return The [TextChannelBehavior] for the channel + */ public fun textChannel(guildId: Snowflake, id: Snowflake): TextChannelBehavior = TextChannelBehavior(guildId = guildId, id = id, kord = kord) + /** + * Returns a [VoiceChannelBehavior] for a given [id] + * + * @param guildId The ID of the guild the channel is in + * @param id The ID of the channel + * @return The [VoiceChannelBehavior] for the channel + */ public fun voiceChannel(guildId: Snowflake, id: Snowflake): VoiceChannelBehavior = VoiceChannelBehavior(guildId = guildId, id = id, kord = kord) + /** + * Returns a [ThreadParentChannelBehavior] for a given [id] + * + * @param guildId The ID of the guild the thread parent is in + * @param id The ID of the channel + * @return The [ThreadParentChannelBehavior] for the channel + */ public fun publicThreadParent(guildId: Snowflake, id: Snowflake): ThreadParentChannelBehavior = ThreadParentChannelBehavior(guildId, id, kord) + /** + * Returns a [PrivateThreadParentChannelBehavior] for a given [id] + * + * @param guildId The ID of the guild the thread parent is in + * @param id The ID of the channel + * @return The [PrivateThreadParentChannelBehavior] for the channel + */ public fun privateThreadParent(guildId: Snowflake, id: Snowflake): PrivateThreadParentChannelBehavior = PrivateThreadParentChannelBehavior(guildId, id, kord) + /** + * Returns a [ThreadChannelBehavior] for a given [id] + * + * @param guildId The ID of the guild the thread parent is in + * @param parentId The ID of the parent channel for the thread + * @param id The ID of the channel + * @return The [ThreadChannelBehavior] for the channel + */ public fun thread(guildId: Snowflake, parentId: Snowflake, id: Snowflake): ThreadChannelBehavior = ThreadChannelBehavior(guildId, parentId, id, kord) - + /** + * Returns a [GuildBehavior] for a given [id] + * + * @param id The ID of the guild + * @return The [GuildBehavior] for the ID + */ public fun guild(id: Snowflake): GuildBehavior = GuildBehavior(id, kord) + /** + * Returns a [GuildEmojiBehavior] for a given [id] + * + * @param guildId The ID of the guild the emoji is in + * @param id The ID of the emoji + * @param kord The Kord instance for the bot + * @return The [GuildEmojiBehavior] for the ID + */ public fun guildEmoji(guildId: Snowflake, id: Snowflake, kord: Kord): GuildEmojiBehavior = GuildEmojiBehavior(guildId = guildId, id = id, kord = kord) + /** + * Returns a [RoleBehavior] for a given [id] + * + * @param guildId The ID of the guild the role is in + * @param id The ID of the role + * @return The [RoleBehavior] for the ID + */ public fun role(guildId: Snowflake, id: Snowflake): RoleBehavior = RoleBehavior(guildId = guildId, id = id, kord = kord) + /** + * Returns a [UserBehavior] for a given [id] + * + * @param id The ID of the user + * @return The [UserBehavior] for the ID + */ public fun user(id: Snowflake): UserBehavior = UserBehavior(id, kord) + /** + * Returns a [ThreadMemberBehavior] for a given [id] + * + * @param id The ID of the user + * @param threadId The ID of the thread + * @return The [ThreadMemberBehavior] for the ID + */ public fun threadMember(id: Snowflake, threadId: Snowflake): ThreadMemberBehavior = ThreadMemberBehavior(id, threadId, kord) + /** + * Returns a [MemberBehavior] for a given [id] + * + * @param guildId The ID of the guild the member is in + * @param id The ID of the user + * @return The [MemberBehavior] for the ID + */ public fun member(guildId: Snowflake, id: Snowflake): MemberBehavior = MemberBehavior(guildId = guildId, id = id, kord = kord) + /** + * Returns a [WebhookBehavior] for a given [id] + * + * @param id The ID of the guild + * @return The [WebhookBehavior] for the ID + */ public fun webhook(id: Snowflake): WebhookBehavior = WebhookBehavior(id, kord) + /** + * Returns a [StageInstanceBehavior] for a given [id] + * + * @param id The ID of the stage instance + * @param channelId The ID of the channel the instance is in + * @return The [StageInstanceBehavior] for the ID + */ public fun stageInstance(id: Snowflake, channelId: Snowflake): StageInstanceBehavior = StageInstanceBehavior( id, channelId, kord, kord.defaultSupplier ) + /** + * Returns a [ApplicationCommandInteractionBehavior] for a given [id] + * + * @param id The ID of the application command + * @param channelId The ID of the channel the interaction took place in + * @param token The interactions token + * @param applicationId The ID of the application the interaction happened with + * @return The [ApplicationCommandInteractionBehavior] for the ID + */ public fun applicationCommandInteraction( id: Snowflake, channelId: Snowflake, @@ -123,7 +316,13 @@ public class Unsafe(private val kord: Kord) { return ApplicationCommandInteractionBehavior(id, channelId, token, applicationId, kord) } - + /** + * Returns a [GlobalApplicationCommandBehavior] for a given [id] + * + * @param applicationId The ID of the application the interaction happened with + * @param id The ID of the application command + * @return The [GlobalApplicationCommandBehavior] for the ID + */ public fun globalApplicationCommand( applicationId: Snowflake, id: Snowflake @@ -132,6 +331,14 @@ public class Unsafe(private val kord: Kord) { } + /** + * Returns a [GuildApplicationCommandBehavior] for a given [id] + * + * @param applicationId The ID of the application the interaction happened with + * @param guildId The ID of the guild the interaction happened in + * @param id The ID of the application command + * @return The [GuildApplicationCommandBehavior] for the ID + */ public fun globalApplicationCommand( applicationId: Snowflake, guildId: Snowflake, @@ -145,6 +352,15 @@ public class Unsafe(private val kord: Kord) { return "Unsafe" } + /** + * Returns a [GuildApplicationCommandBehavior] for a given [commandId] + * + * @param guildId The ID of the guild the interaction happened in + * @param applicationId The ID of the application the interaction happened with + * @param commandId The ID of the application command + * @param service The interaction service for the command + * @return The [GuildApplicationCommandBehavior] for the ID + */ public fun guildApplicationCommand( guildId: Snowflake, applicationId: Snowflake, @@ -153,6 +369,14 @@ public class Unsafe(private val kord: Kord) { ): GuildApplicationCommandBehavior = GuildApplicationCommandBehavior(guildId, applicationId, commandId, service) + /** + * Returns a [GlobalApplicationCommandBehavior] for a given [commandId] + * + * @param applicationId The ID of the application the interaction happened with + * @param commandId The ID of the application command + * @param service The interaction service for the command + * @return The [GlobalApplicationCommandBehavior] for the ID + */ public fun globalApplicationCommand( applicationId: Snowflake, commandId: Snowflake, @@ -173,6 +397,13 @@ public class Unsafe(private val kord: Kord) { id, channelId, token, applicationId, kord ) + /** + * Returns a [GuildScheduledEventBehavior] for a given [id] + * + * @param id The ID of the event + * @param guildId The ID of the event the guild is for + * @return The [GuildScheduledEventBehavior] for the ID + */ public fun guildScheduledEvent(id: Snowflake, guildId: Snowflake): GuildScheduledEventBehavior = GuildScheduledEventBehavior( id, From 7eb90425345726076097d70cf77dedb4ab06acc9 Mon Sep 17 00:00:00 2001 From: NoComment Date: Tue, 21 Feb 2023 19:06:04 +0000 Subject: [PATCH 09/17] Document the exception, supplier and builder packages for the core package --- .../component/ButtonBuilderExtensions.kt | 16 +- .../main/kotlin/builder/kord/KordBuilder.kt | 10 + .../kotlin/builder/kord/RestOnlyBuilder.kt | 9 + .../exception/EntityNotFoundException.kt | 166 +++++++++- .../exception/GatewayNotFoundException.kt | 3 + .../exception/KordInitializationException.kt | 3 + .../kotlin/supplier/CacheEntitySupplier.kt | 3 + .../main/kotlin/supplier/EntitySupplier.kt | 286 +++++++++++++++++- .../kotlin/supplier/RestEntitySupplier.kt | 62 +++- 9 files changed, 552 insertions(+), 6 deletions(-) diff --git a/core/src/main/kotlin/builder/component/ButtonBuilderExtensions.kt b/core/src/main/kotlin/builder/component/ButtonBuilderExtensions.kt index e634061dcb17..710bd3face2b 100644 --- a/core/src/main/kotlin/builder/component/ButtonBuilderExtensions.kt +++ b/core/src/main/kotlin/builder/component/ButtonBuilderExtensions.kt @@ -6,15 +6,29 @@ import dev.kord.core.entity.GuildEmoji import dev.kord.core.entity.ReactionEmoji import dev.kord.rest.builder.component.ButtonBuilder - +/** + * Sets the emoji that appears on the button. + * + * @param emoji The [ReactionEmoji.Unicode] for the emoji + */ public fun ButtonBuilder.emoji(emoji: ReactionEmoji.Unicode) { this.emoji = DiscordPartialEmoji(name = emoji.name, id = null) } +/** + * Sets the emoji that appears on the button. + * + * @param emoji The [ReactionEmoji.Custom] for the emoji + */ public fun ButtonBuilder.emoji(emoji: ReactionEmoji.Custom) { this.emoji = DiscordPartialEmoji(name = emoji.name, id = emoji.id, animated = emoji.isAnimated.optional()) } +/** + * Sets the emoji that appears on the button. + * + * @param emoji The [GuildEmoji] for the emoji + */ public fun ButtonBuilder.emoji(emoji: GuildEmoji) { this.emoji = DiscordPartialEmoji(id = emoji.id, name = null, animated = emoji.isAnimated.optional()) } diff --git a/core/src/main/kotlin/builder/kord/KordBuilder.kt b/core/src/main/kotlin/builder/kord/KordBuilder.kt index ee366b96bfa9..f982625e18e5 100644 --- a/core/src/main/kotlin/builder/kord/KordBuilder.kt +++ b/core/src/main/kotlin/builder/kord/KordBuilder.kt @@ -64,6 +64,11 @@ public operator fun DefaultGateway.Companion.invoke( private val logger = KotlinLogging.logger { } private val gatewayInfoJson = Json { ignoreUnknownKeys = true } +/** + * The builder for the [Kord] instance. + * + * @property token The bots token + */ public class KordBuilder(public val token: String) { private var shardsBuilder: (recommended: Int) -> Shards = { Shards(it) } private var gatewayBuilder: (resources: ClientResources, shards: List) -> List = @@ -123,6 +128,9 @@ public class KordBuilder(public val token: String) { */ public var httpClient: HttpClient? = null + /** + * The [Snowflake] ID for the application. + */ public var applicationId: Snowflake? = null /** @@ -234,6 +242,8 @@ public class KordBuilder(public val token: String) { } /** + * Builds the [Kord] instance + * * @throws KordInitializationException if something went wrong while getting the bot's gateway information. */ public suspend fun build(): Kord { diff --git a/core/src/main/kotlin/builder/kord/RestOnlyBuilder.kt b/core/src/main/kotlin/builder/kord/RestOnlyBuilder.kt index 9d240dc75cf2..30cd98cb66d9 100644 --- a/core/src/main/kotlin/builder/kord/RestOnlyBuilder.kt +++ b/core/src/main/kotlin/builder/kord/RestOnlyBuilder.kt @@ -19,6 +19,9 @@ import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.ExperimentalCoroutinesApi import kotlinx.coroutines.flow.MutableSharedFlow +/** + * The Builder for the RestOnly client + */ public abstract class RestOnlyBuilder { protected var handlerBuilder: (resources: ClientResources) -> RequestHandler = { KtorRequestHandler(it.httpClient, ExclusionRequestRateLimiter(), token = it.token) } @@ -36,6 +39,9 @@ public abstract class RestOnlyBuilder { */ public var httpClient: HttpClient? = null + /** + * The [Snowflake] ID for the application + */ public abstract var applicationId: Snowflake /** @@ -51,6 +57,9 @@ public abstract class RestOnlyBuilder { this.handlerBuilder = handlerBuilder } + /** + * Builds the rest only [Kord] instance + */ public fun build(): Kord { val client = httpClient.configure() val selfId = applicationId diff --git a/core/src/main/kotlin/exception/EntityNotFoundException.kt b/core/src/main/kotlin/exception/EntityNotFoundException.kt index a8747b3cf664..da999bcc86a6 100644 --- a/core/src/main/kotlin/exception/EntityNotFoundException.kt +++ b/core/src/main/kotlin/exception/EntityNotFoundException.kt @@ -4,6 +4,9 @@ import dev.kord.common.entity.Snowflake import dev.kord.core.entity.application.ApplicationCommand import dev.kord.core.entity.channel.Channel +/** + * Thrown when an Entity cannot be found. + */ public class EntityNotFoundException : Exception { public constructor(message: String) : super(message) @@ -13,45 +16,132 @@ public class EntityNotFoundException : Exception { @Suppress("NOTHING_TO_INLINE") public companion object { + /** + * Indicates an Entity cannot be found + * + * @param entityType The type of entity that cannot be found + * @param id The ID of the entity that was not found + * @throws EntityNotFoundException + */ @PublishedApi internal inline fun entityNotFound(entityType: String, id: Snowflake): Nothing = throw EntityNotFoundException("$entityType with id $id was not found.") + /** + * Indicates a Guild Entity cannot be found + * + * @param entityType The type of entity that cannot be found + * @param guildId The ID of the guild that cannot be found + * @param id The ID of the entity that was not found + * @throws EntityNotFoundException + */ @PublishedApi internal inline fun guildEntityNotFound(entityType: String, guildId: Snowflake, id: Snowflake): Nothing = throw EntityNotFoundException("$entityType with id $id in guild $guildId was not found.") - + /** + * Indicates a guild was not found. + * + * @param guildId The ID of the guild that was not found + * @throws EntityNotFoundException + */ public inline fun guildNotFound(guildId: Snowflake): Nothing = entityNotFound("Guild", guildId) + /** + * Indicates a channel was not found. + * + * @param channelId The ID of the channel that was not found + * @throws EntityNotFoundException + */ public inline fun channelNotFound(channelId: Snowflake): Nothing = entityNotFound(T::class.simpleName!!, channelId) + /** + * Indicates a member was not found. + * + * @param guildId The ID of the guild + * @param userId The ID of the member that was not found + * @throws EntityNotFoundException + */ public inline fun memberNotFound(guildId: Snowflake, userId: Snowflake): Nothing = guildEntityNotFound("Member", guildId = guildId, id = userId) + /** + * Indicates a message was not found. + * + * @param channelId The ID of the channel + * @param messageId The ID of the message that was not found + * @throws EntityNotFoundException + */ public inline fun messageNotFound(channelId: Snowflake, messageId: Snowflake): Nothing = throw EntityNotFoundException("Message with id $messageId in channel $channelId was not found.") + /** + * Indicates a user was not found. + * + * @param userId The ID of the user that was not found + * @throws EntityNotFoundException + */ public inline fun userNotFound(userId: Snowflake): Nothing = entityNotFound("User", userId) + /** + * Indicates the self user was not found. + * + * @throws EntityNotFoundException + */ public inline fun selfNotFound(): Nothing = throw EntityNotFoundException("Self user was not found.") + /** + * Indicates a role was not found. + * + * @param guildId The ID of the guild + * @param roleId The ID of the role that was not found + * @throws EntityNotFoundException + */ public inline fun roleNotFound(guildId: Snowflake, roleId: Snowflake): Nothing = guildEntityNotFound("Role", guildId = guildId, id = roleId) + /** + * Indicates a ban was not found. + * + * @param guildId The ID of the guild + * @param userId The ID of the user + * @throws EntityNotFoundException + */ public inline fun banNotFound(guildId: Snowflake, userId: Snowflake): Nothing = guildEntityNotFound("Ban", guildId = guildId, id = userId) + /** + * Indicates an emoji was not found. + * + * @param guildId The ID of the guild + * @param emojiId The ID of the emoji that was not found + * @throws EntityNotFoundException + */ public inline fun emojiNotFound(guildId: Snowflake, emojiId: Snowflake): Nothing = guildEntityNotFound("GuildEmoji", guildId = guildId, id = emojiId) + /** + * Indicates a webhook was not found. + * + * @param webhookId The ID of the webhook that was not found + * @throws EntityNotFoundException + */ public inline fun webhookNotFound(webhookId: Snowflake): Nothing = entityNotFound("Webhook", webhookId) + /** + * Indicates a webhook was not found. + * + * @param webhookId The ID of the webhook that was not found + * @param token The token for the interaction + * @param messageId The ID of the message that was not found + * @param threadId The ID of the thread the webhook was not found in, or null if this is a channel + * @throws EntityNotFoundException + */ public inline fun webhookMessageNotFound( webhookId: Snowflake, token: String, @@ -63,42 +153,116 @@ public class EntityNotFoundException : Exception { }from webhook $webhookId with token $token was not found." ) + /** + * Indicates an invite was not found. + * + * @param code The code of the invite that was not found + * @throws EntityNotFoundException + */ public inline fun inviteNotFound(code: String): Nothing = throw EntityNotFoundException("Invite with code $code was not found.") + /** + * Indicates a widget was not found. + * + * @param id The ID of the widget that was not found + * @throws EntityNotFoundException + */ public inline fun widgetNotFound(id: Snowflake): Nothing = throw EntityNotFoundException("Widget for guild ${id.value} was not found.") + /** + * Indicates a template was not found. + * + * @param code The code of the template that was not found + * @throws EntityNotFoundException + */ public inline fun templateNotFound(code: String): Nothing = throw EntityNotFoundException("Template $code was not found.") + /** + * Indicates a welcome screen was not found. + * + * @param guildId The ID of the guild the screen was not found + * @throws EntityNotFoundException + */ public inline fun welcomeScreenNotFound(guildId: Snowflake): Nothing = throw EntityNotFoundException("Welcome screen for guild $guildId was not found.") + /** + * Indicates a state instance was not found. + * + * @param channelId The ID of the channel that was not found + * @throws EntityNotFoundException + */ public inline fun stageInstanceNotFound(channelId: Snowflake): Nothing = throw EntityNotFoundException("Stage instance for channel $channelId was not found.") + /** + * Indicates a sticker was not found. + * + * @param stickerId The ID of the sticker that was not found + * @throws EntityNotFoundException + */ public inline fun stickerNotFound(stickerId: Snowflake): Nothing = entityNotFound("Sticker", stickerId) + /** + * Indicates an application command permission was not found. + * + * @param commandId The ID of the command that was not found + * @throws EntityNotFoundException + */ public inline fun applicationCommandPermissionsNotFound(commandId: Snowflake): Nothing = entityNotFound("ApplicationCommand", commandId) + /** + * Indicates an event was not found. + * + * @param eventId The ID of the event that was not found + * @throws EntityNotFoundException + */ public inline fun guildScheduledEventNotFound(eventId: Snowflake): Nothing = entityNotFound("GuildScheduledEvent", eventId) + /** + * Indicates a guild was not found. + * + * @param guildId The ID of the guild that was not found + * @throws EntityNotFoundException + */ public inline fun applicationCommandNotFound(commandId: Snowflake): Nothing = entityNotFound(T::class.simpleName!!, commandId) + /** + * Indicates an interaction was not found. + * + * @param token The ID of the interaction that was not found + * @throws EntityNotFoundException + */ public inline fun interactionNotFound(token: String): Nothing = throw EntityNotFoundException( "Initial interaction response for interaction with token $token was not found." ) + /** + * Indicates a followup message was not found. + * + * @param token The ID of the interaction + * @param messageId The ID of the message that was not found + * @throws EntityNotFoundException + */ public inline fun followupMessageNotFound(token: String, messageId: Snowflake): Nothing = throw EntityNotFoundException( "Followup message with id $messageId for interaction with token $token was not found." ) + /** + * Indicates an auto-moderation rule was not found. + * + * @param guildId The ID of the guild + * @param ruleId The ID rule that was not found + * @throws EntityNotFoundException + */ public inline fun autoModerationRuleNotFound(guildId: Snowflake, ruleId: Snowflake): Nothing = guildEntityNotFound("Auto Moderation Rule", guildId, ruleId) } diff --git a/core/src/main/kotlin/exception/GatewayNotFoundException.kt b/core/src/main/kotlin/exception/GatewayNotFoundException.kt index c16592b1f470..c195e07aade4 100644 --- a/core/src/main/kotlin/exception/GatewayNotFoundException.kt +++ b/core/src/main/kotlin/exception/GatewayNotFoundException.kt @@ -2,6 +2,9 @@ package dev.kord.core.exception import dev.kord.common.entity.Snowflake +/** + * Thrown when a Gateway cannot be found. + */ public class GatewayNotFoundException : Exception { public constructor(message: String) : super(message) public constructor(cause: Throwable) : super(cause) diff --git a/core/src/main/kotlin/exception/KordInitializationException.kt b/core/src/main/kotlin/exception/KordInitializationException.kt index c6570a3723fa..729f526e77c3 100644 --- a/core/src/main/kotlin/exception/KordInitializationException.kt +++ b/core/src/main/kotlin/exception/KordInitializationException.kt @@ -1,5 +1,8 @@ package dev.kord.core.exception +/** + * Thrown when Kord cannot successfully initialize. + */ public class KordInitializationException : Exception { public constructor(message: String) : super(message) public constructor(cause: Throwable) : super(cause) diff --git a/core/src/main/kotlin/supplier/CacheEntitySupplier.kt b/core/src/main/kotlin/supplier/CacheEntitySupplier.kt index 1cb1c886cb21..8fd6f1deb3c9 100644 --- a/core/src/main/kotlin/supplier/CacheEntitySupplier.kt +++ b/core/src/main/kotlin/supplier/CacheEntitySupplier.kt @@ -98,6 +98,9 @@ public class CacheEntitySupplier(private val kord: Kord) : EntitySupplier { Member(it, userData, kord) } + /** + * fetches all cached [Role]s + */ public suspend fun getRole(id: Snowflake): Role? { val data = cache.query { idEq(RoleData::id, id) }.singleOrNull() ?: return null diff --git a/core/src/main/kotlin/supplier/EntitySupplier.kt b/core/src/main/kotlin/supplier/EntitySupplier.kt index 153ad6190d75..8f30143dec65 100644 --- a/core/src/main/kotlin/supplier/EntitySupplier.kt +++ b/core/src/main/kotlin/supplier/EntitySupplier.kt @@ -445,43 +445,141 @@ public interface EntitySupplier { public suspend fun getTemplate(code: String): Template = getTemplateOrNull(code) ?: EntityNotFoundException.templateNotFound(code) + /** + * Requests the templates for a guild + * + * @param guildId The ID of the guild to get the templates from + * @return a [Flow] of [Template]s for the given [guildId]. + * @throws RequestException if something went wrong while retrieving the templates + */ public fun getTemplates(guildId: Snowflake): Flow