Merge pull request #87 from DisgoOrg/docs

docs improvements

core/application_command.go

@@ -174,7 +174,7 @@ func (c *MessageCommand) ToCreate() discord.MessageCommandCreate {
 	}
 }
 
-// Update updates the current ApplicationCommand with the given fields
+// Update updates the current ApplicationCommand with the given discord.ApplicationCommandUpdate
 func (c *MessageCommand) Update(commandUpdate discord.MessageCommandUpdate, opts ...rest.RequestOpt) (*MessageCommand, error) {
 	var command discord.ApplicationCommand
 	var err error

core/audio_controller.go

@@ -10,7 +10,7 @@ type AudioController interface {
 	// Bot returns the core.Bot instance
 	Bot() *Bot
 
-	// Connect sends a discord.GatewayCommand to connect to a Channel
+	// Connect sends a discord.GatewayCommand to connect to the specified Channel
 	Connect(guildID discord.Snowflake, channelID discord.Snowflake) error
 
 	// Disconnect sends a discord.GatewayCommand to disconnect from a Channel

core/ban.go

@@ -13,6 +13,7 @@ type Ban struct {
 	GuildID discord.Snowflake
 }
 
+// Unban unbans the User associated with this Ban from the Guild
 func (b *Ban) Unban(opts ...rest.RequestOpt) error {
 	return b.Bot.RestServices.GuildService().DeleteBan(b.GuildID, b.User.ID, opts...)
 }

core/bot.go

@@ -95,11 +95,12 @@ func (b *Bot) ConnectShardManager(ctx context.Context) error {
 	return b.ShardManager.Open(ctx)
 }
 
-// HasGateway returns whether core.disgo has an active gateway.Gateway connection
+// HasGateway returns whether this Bot has an active gateway.Gateway connection
 func (b *Bot) HasGateway() bool {
 	return b.Gateway != nil
 }
 
+// HasShardManager returns whether this Bot is sharded
 func (b *Bot) HasShardManager() bool {
 	return b.ShardManager != nil
 }
@@ -124,6 +125,7 @@ func (b *Bot) SetPresence(presenceUpdate discord.PresenceUpdate) error {
 	return b.Gateway.Send(discord.NewGatewayCommand(discord.GatewayOpcodePresenceUpdate, presenceUpdate))
 }
 
+// SetPresenceForShard sets the Presence of this Bot for the provided shard
 func (b *Bot) SetPresenceForShard(shardId int, presenceUpdate discord.PresenceUpdate) error {
 	if !b.HasShardManager() {
 		return discord.ErrNoShardManager

core/bot/config.go

@@ -9,6 +9,7 @@ import (
 	"github.com/DisgoOrg/log"
 )
 
+// Config lets you configure your Bot instance
 // Config is the core.Bot config used to configure everything
 type Config struct {
 	Logger log.Logger
@@ -49,6 +50,7 @@ func (c *Config) Apply(opts []ConfigOpt) {
 	}
 }
 
+// WithLogger lets you inject your own logger implementing log.Logger
 //goland:noinspection GoUnusedExportedFunction
 func WithLogger(logger log.Logger) ConfigOpt {
 	return func(config *Config) {

core/events/events_dm_message_event.go

@@ -5,34 +5,34 @@ import (
 	"github.com/DisgoOrg/disgo/discord"
 )
 
-// GenericDMMessageEvent is called upon receiving DMMessageCreateEvent, DMMessageUpdateEvent, DMMessageDeleteEvent, GenericDMMessageReactionEvent, DMMessageReactionAddEvent, DMMessageReactionRemoveEvent, DMMessageReactionRemoveEmojiEvent or DMMessageReactionRemoveAllEvent(requires core.GatewayIntentsDirectMessages)
+// GenericDMMessageEvent is called upon receiving DMMessageCreateEvent, DMMessageUpdateEvent, DMMessageDeleteEvent, GenericDMMessageReactionEvent, DMMessageReactionAddEvent, DMMessageReactionRemoveEvent, DMMessageReactionRemoveEmojiEvent or DMMessageReactionRemoveAllEvent (requires discord.GatewayIntentsDirectMessage)
 type GenericDMMessageEvent struct {
 	*GenericEvent
 	MessageID discord.Snowflake
 	Message   *core.Message
 	ChannelID discord.Snowflake
 }
 
-// Channel returns the core.DMChannel where the GenericDMMessageEvent happened
+// Channel returns the Channel the GenericDMMessageEvent happened in
 func (e GenericDMMessageEvent) Channel() *core.DMChannel {
 	if ch := e.Bot().Caches.Channels().Get(e.ChannelID); ch != nil {
 		return ch.(*core.DMChannel)
 	}
 	return nil
 }
 
-// DMMessageCreateEvent is called upon receiving an core.Message in an core.DMChannel(requires core.GatewayIntentsDirectMessages)
+// DMMessageCreateEvent is called upon receiving a core.Message in a Channel (requires discord.GatewayIntentsDirectMessage)
 type DMMessageCreateEvent struct {
 	*GenericDMMessageEvent
 }
 
-// DMMessageUpdateEvent is called upon editing an core.Message in an core.DMChannel(requires core.GatewayIntentsDirectMessages)
+// DMMessageUpdateEvent is called upon editing a core.Message in a Channel (requires discord.GatewayIntentsDirectMessage)
 type DMMessageUpdateEvent struct {
 	*GenericDMMessageEvent
 	OldMessage *core.Message
 }
 
-// DMMessageDeleteEvent is called upon deleting an core.Message in an core.DMChannel(requires core.GatewayIntentsDirectMessages)
+// DMMessageDeleteEvent is called upon deleting a core.Message in a Channel (requires discord.GatewayIntentsDirectMessage)
 type DMMessageDeleteEvent struct {
 	*GenericDMMessageEvent
 }

core/events/events_dm_message_reaction.go

@@ -5,7 +5,7 @@ import (
 	"github.com/DisgoOrg/disgo/discord"
 )
 
-// GenericDMMessageReactionEvent is called upon receiving DMMessageReactionAddEvent or DMMessageReactionRemoveEvent(requires the core.GatewayIntentsDirectMessageReactions)
+// GenericDMMessageReactionEvent is called upon receiving DMMessageReactionAddEvent or DMMessageReactionRemoveEvent (requires the discord.GatewayIntentDirectMessageReactions)
 type GenericDMMessageReactionEvent struct {
 	*GenericEvent
 	UserID    discord.Snowflake
@@ -14,29 +14,31 @@ type GenericDMMessageReactionEvent struct {
 	Emoji     discord.ReactionEmoji
 }
 
+// User returns the User who owns the discord.MessageReaction.
+// This will only check cached users!
 func (e *GenericDMMessageReactionEvent) User() *core.User {
 	return e.Bot().Caches.Users().Get(e.UserID)
 }
 
-// DMMessageReactionAddEvent indicates that an core.User added an core.MessageReaction to an core.Message in an core.DMChannel(requires the core.GatewayIntentsDirectMessageReactions)
+// DMMessageReactionAddEvent indicates that a core.User added a discord.MessageReaction to a core.Message in a Channel (requires the discord.GatewayIntentDirectMessageReactions)
 type DMMessageReactionAddEvent struct {
 	*GenericDMMessageReactionEvent
 }
 
-// DMMessageReactionRemoveEvent indicates that an core.User removed an core.MessageReaction from an core.Message in an core.DMChannel(requires the core.GatewayIntentsDirectMessageReactions)
+// DMMessageReactionRemoveEvent indicates that a core.User removed a discord.MessageReaction from a core.Message in a Channel (requires the discord.GatewayIntentDirectMessageReactions)
 type DMMessageReactionRemoveEvent struct {
 	*GenericDMMessageReactionEvent
 }
 
-// DMMessageReactionRemoveEmojiEvent indicates someone removed all core.MessageReaction of a specific core.Emoji from an core.Message in an core.DMChannel(requires the core.GatewayIntentsDirectMessageReactions)
+// DMMessageReactionRemoveEmojiEvent indicates someone removed all discord.MessageReaction(s) of a specific core.Emoji from a core.Message in a Channel (requires the discord.GatewayIntentDirectMessageReactions)
 type DMMessageReactionRemoveEmojiEvent struct {
 	*GenericEvent
 	ChannelID discord.Snowflake
 	MessageID discord.Snowflake
 	Emoji     discord.ReactionEmoji
 }
 
-// DMMessageReactionRemoveAllEvent indicates someone removed all core.MessageReaction(s) from an core.Message in an core.DMChannel(requires the core.GatewayIntentsDirectMessageReactions)
+// DMMessageReactionRemoveAllEvent indicates someone removed all discord.MessageReaction(s) from a core.Message in a Channel (requires the discord.GatewayIntentDirectMessageReactions)
 type DMMessageReactionRemoveAllEvent struct {
 	*GenericEvent
 	ChannelID discord.Snowflake

core/events/events_gateway_status.go

@@ -4,13 +4,13 @@ import (
 	"github.com/DisgoOrg/disgo/discord"
 )
 
-// ReadyEvent indicates we received the ReadyEvent from the core.Gateway
+// ReadyEvent indicates we received the ReadyEvent from the gateway.Gateway
 type ReadyEvent struct {
 	*GenericEvent
 	discord.GatewayEventReady
 }
 
-// ResumedEvent indicates disgo resumed to the core.Gateway
+// ResumedEvent indicates disgo resumed the gateway.Gateway
 type ResumedEvent struct {
 	*GenericEvent
 }
@@ -20,7 +20,7 @@ type InvalidSessionEvent struct {
 	MayResume bool
 }
 
-// DisconnectedEvent indicates disgo disconnected to the core.Gateway
+// DisconnectedEvent indicates disgo disconnected from the gateway.Gateway
 type DisconnectedEvent struct {
 	*GenericEvent
 }

core/events/events_guild_channel.go

@@ -13,23 +13,24 @@ type GenericGuildChannelEvent struct {
 	GuildID   discord.Snowflake
 }
 
-// Guild returns the cached core.Guild the event happened in
+// Guild returns the core.Guild the event happened in.
+// This will only check cached guilds!
 func (e GenericGuildChannelEvent) Guild() *core.Guild {
 	return e.Bot().Caches.Guilds().Get(e.GuildID)
 }
 
-// GuildChannelCreateEvent indicates that a new core.GetGuildChannel got created in an core.Guild
+// GuildChannelCreateEvent indicates that a new Channel got created in a core.Guild
 type GuildChannelCreateEvent struct {
 	*GenericGuildChannelEvent
 }
 
-// GuildChannelUpdateEvent indicates that an core.GetGuildChannel got updated in an core.Guild
+// GuildChannelUpdateEvent indicates that a Channel got updated in a core.Guild
 type GuildChannelUpdateEvent struct {
 	*GenericGuildChannelEvent
 	OldChannel core.GuildChannel
 }
 
-// GuildChannelDeleteEvent indicates that an core.GetGuildChannel got deleted in an core.Guild
+// GuildChannelDeleteEvent indicates that a Channel got deleted in a core.Guild
 type GuildChannelDeleteEvent struct {
 	*GenericGuildChannelEvent
 }

core/events/events_guild_emoji.go

@@ -5,25 +5,25 @@ import (
 	"github.com/DisgoOrg/disgo/discord"
 )
 
-// GenericEmojiEvent is called upon receiving EmojiCreateEvent, EmojiUpdateEvent or EmojiDeleteEvent(requires core.GatewayIntentsGuildEmojis)
+// GenericEmojiEvent is called upon receiving EmojiCreateEvent, EmojiUpdateEvent or EmojiDeleteEvent (requires discord.GatewayIntentGuildEmojisAndStickers)
 type GenericEmojiEvent struct {
 	*GenericEvent
 	GuildID discord.Snowflake
 	Emoji   *core.Emoji
 }
 
-// EmojiCreateEvent indicates that a new core.Emoji got created in an core.Guild(requires core.GatewayIntentsGuildEmojis)
+// EmojiCreateEvent indicates that a new core.Emoji got created in a core.Guild (requires discord.GatewayIntentGuildEmojisAndStickers)
 type EmojiCreateEvent struct {
 	*GenericEmojiEvent
 }
 
-// EmojiUpdateEvent indicates that an core.Emoji got updated in an core.Guild(requires core.GatewayIntentsGuildEmojis)
+// EmojiUpdateEvent indicates that a core.Emoji got updated in a core.Guild (requires discord.GatewayIntentGuildEmojisAndStickers)
 type EmojiUpdateEvent struct {
 	*GenericEmojiEvent
 	OldEmoji *core.Emoji
 }
 
-// EmojiDeleteEvent indicates that an core.Emoji got deleted in an core.Guild(requires core.GatewayIntentsGuildEmojis)
+// EmojiDeleteEvent indicates that a core.Emoji got deleted in a core.Guild (requires discord.GatewayIntentGuildEmojisAndStickers)
 type EmojiDeleteEvent struct {
 	*GenericEmojiEvent
 }

core/events/events_guild_invite.go

@@ -5,29 +5,29 @@ import (
 	"github.com/DisgoOrg/disgo/discord"
 )
 
-// GenericGuildInviteEvent is called upon receiving GuildInviteCreateEvent or GuildInviteDeleteEvent(requires core.GatewayIntentsGuildInvites)
+// GenericGuildInviteEvent is called upon receiving GuildInviteCreateEvent or GuildInviteDeleteEvent (requires discord.GatewayIntentGuildInvites)
 type GenericGuildInviteEvent struct {
 	*GenericEvent
 	GuildID   discord.Snowflake
 	ChannelID discord.Snowflake
 	Code      string
 }
 
-// Channel returns the core.GuildChannel the GenericGuildInviteEvent happened in(returns nil if the core.GetChannel is uncached or core.Caches is disabled)
+// Channel returns the Channel the GenericGuildInviteEvent happened in.
 func (e GenericGuildInviteEvent) Channel() core.GuildChannel {
 	if ch := e.Bot().Caches.Channels().Get(e.ChannelID); ch != nil {
 		return ch.(core.GuildChannel)
 	}
 	return nil
 }
 
-// GuildInviteCreateEvent is called upon creation of a new core.Invite in an core.Guild(requires core.GatewayIntentsGuildInvites)
+// GuildInviteCreateEvent is called upon creation of a new core.Invite in a core.Guild (requires discord.GatewayIntentGuildInvites)
 type GuildInviteCreateEvent struct {
 	*GenericGuildInviteEvent
 	Invite *core.Invite
 }
 
-// GuildInviteDeleteEvent is called upon deletion of a new core.Invite in an core.Guild(requires core.GatewayIntentsGuildInvites)
+// GuildInviteDeleteEvent is called upon deletion of a core.Invite in a core.Guild (requires discord.GatewayIntentGuildInvites)
 type GuildInviteDeleteEvent struct {
 	*GenericGuildInviteEvent
 }

core/events/events_guild_message.go

@@ -14,7 +14,8 @@ type GenericGuildMessageEvent struct {
 	GuildID   discord.Snowflake
 }
 
-// Guild returns the core.Guild the GenericGuildMessageEvent happened in
+// Guild returns the core.Guild the GenericGuildMessageEvent happened in.
+// This will only check cached guilds!
 func (e GenericGuildMessageEvent) Guild() *core.Guild {
 	return e.Bot().Caches.Guilds().Get(e.GuildID)
 }
@@ -27,18 +28,18 @@ func (e GenericGuildMessageEvent) Channel() core.GuildMessageChannel {
 	return nil
 }
 
-// GuildMessageCreateEvent is called upon receiving an core.Message in an core.DMChannel
+// GuildMessageCreateEvent is called upon receiving a core.Message in a Channel
 type GuildMessageCreateEvent struct {
 	*GenericGuildMessageEvent
 }
 
-// GuildMessageUpdateEvent is called upon editing an core.Message in an core.DMChannel
+// GuildMessageUpdateEvent is called upon editing a core.Message in a Channel
 type GuildMessageUpdateEvent struct {
 	*GenericGuildMessageEvent
 	OldMessage *core.Message
 }
 
-// GuildMessageDeleteEvent is called upon deleting an core.Message in an core.DMChannel
+// GuildMessageDeleteEvent is called upon deleting a core.Message in a Channel
 type GuildMessageDeleteEvent struct {
 	*GenericGuildMessageEvent
 }

core/events/events_guild_message_reaction.go

@@ -5,7 +5,7 @@ import (
 	"github.com/DisgoOrg/disgo/discord"
 )
 
-// GenericGuildMessageReactionEvent is called upon receiving DMMessageReactionAddEvent or DMMessageReactionRemoveEvent
+// GenericGuildMessageReactionEvent is called upon receiving GuildMessageReactionAddEvent or GuildMessageReactionRemoveEvent
 type GenericGuildMessageReactionEvent struct {
 	*GenericEvent
 	UserID    discord.Snowflake
@@ -29,12 +29,12 @@ type GuildMessageReactionAddEvent struct {
 	Member *core.Member
 }
 
-// GuildMessageReactionRemoveEvent indicates that an core.Member removed an core.MessageReaction from an core.Message in an core.TextChannel(requires the core.GatewayIntentsGuildMessageReactions)
+// GuildMessageReactionRemoveEvent indicates that a core.Member removed a discord.MessageReaction from a core.Message in a Channel (requires the discord.GatewayIntentGuildMessageReactions)
 type GuildMessageReactionRemoveEvent struct {
 	*GenericGuildMessageReactionEvent
 }
 
-// GuildMessageReactionRemoveEmojiEvent indicates someone removed all core.MessageReaction of a specific core.Emoji from an core.Message in an core.TextChannel(requires the core.GatewayIntentsGuildMessageReactions)
+// GuildMessageReactionRemoveEmojiEvent indicates someone removed all discord.MessageReaction of a specific core.Emoji from a core.Message in a Channel (requires the discord.GatewayIntentGuildMessageReactions)
 type GuildMessageReactionRemoveEmojiEvent struct {
 	*GenericEvent
 	ChannelID discord.Snowflake
@@ -43,7 +43,7 @@ type GuildMessageReactionRemoveEmojiEvent struct {
 	Emoji     discord.ReactionEmoji
 }
 
-// GuildMessageReactionRemoveAllEvent indicates someone removed all core.MessageReaction(s) from an core.Message in an core.TextChannel(requires the core.GatewayIntentsGuildMessageReactions)
+// GuildMessageReactionRemoveAllEvent indicates someone removed all discord.MessageReaction(s) from a core.Message in a Channel (requires the discord.GatewayIntentGuildMessageReactions)
 type GuildMessageReactionRemoveAllEvent struct {
 	*GenericEvent
 	ChannelID discord.Snowflake

core/events/events_guild_sticker.go

@@ -5,25 +5,25 @@ import (
 	"github.com/DisgoOrg/disgo/discord"
 )
 
-// GenericStickerEvent is called upon receiving StickerCreateEvent, StickerUpdateEvent or StickerDeleteEvent(requires core.GatewayIntentsGuildStickers)
+// GenericStickerEvent is called upon receiving StickerCreateEvent, StickerUpdateEvent or StickerDeleteEvent (requires discord.GatewayIntentGuildEmojisAndStickers)
 type GenericStickerEvent struct {
 	*GenericEvent
 	GuildID discord.Snowflake
 	Sticker *core.Sticker
 }
 
-// StickerCreateEvent indicates that a new core.Sticker got created in a core.Guild(requires core.GatewayIntentsGuildStickers)
+// StickerCreateEvent indicates that a new core.Sticker got created in a core.Guild (requires discord.GatewayIntentGuildEmojisAndStickers)
 type StickerCreateEvent struct {
 	*GenericStickerEvent
 }
 
-// StickerUpdateEvent indicates that a core.Sticker got updated in a core.Guild(requires core.GatewayIntentsGuildStickers)
+// StickerUpdateEvent indicates that a core.Sticker got updated in a core.Guild (requires discord.GatewayIntentGuildEmojisAndStickers)
 type StickerUpdateEvent struct {
 	*GenericStickerEvent
 	OldSticker *core.Sticker
 }
 
-// StickerDeleteEvent indicates that a core.Sticker got deleted in a core.Guild(requires core.GatewayIntentsGuildStickers)
+// StickerDeleteEvent indicates that a core.Sticker got deleted in a core.Guild (requires discord.GatewayIntentGuildEmojisAndStickers)
 type StickerDeleteEvent struct {
 	*GenericStickerEvent
 }

core/events/events_guild_webhooks_update.go

@@ -11,6 +11,8 @@ type WebhooksUpdateEvent struct {
 	ChannelID discord.Snowflake
 }
 
+// Guild returns the Guild the webhook was updated in.
+// This will only check cached guilds!
 func (e *WebhooksUpdateEvent) Guild() *core.Guild {
 	return e.Bot().Caches.Guilds().Get(e.GuildId)
 }

core/events/events_heartbeat_event.go

@@ -2,7 +2,7 @@ package events
 
 import "time"
 
-// HeartbeatEvent is called upon sending a heartbeat to the core.Gateway
+// HeartbeatEvent is called upon sending a heartbeat to the gateway.Gateway
 type HeartbeatEvent struct {
 	*GenericEvent
 	NewPing time.Duration

core/events/events_http_request.go

@@ -4,7 +4,7 @@ import (
 	"net/http"
 )
 
-// HTTPRequestEvent indicates a new http.Request was made and can be used to collect data of StatusCodes as an _examples
+// HTTPRequestEvent indicates a new http.Request was made and can be used to collect data of StatusCodes
 type HTTPRequestEvent struct {
 	*GenericEvent
 	Request  *http.Request