From 964060f34c9da77c681647d877e8914bbaa154b7 Mon Sep 17 00:00:00 2001 From: Carson Hoffman Date: Tue, 13 Mar 2018 10:48:50 -0400 Subject: [PATCH] General documentation improvements --- event.go | 11 ++- message.go | 61 +++++++++++---- state.go | 3 +- structs.go | 221 +++++++++++++++++++++++++++++++++++++++++------------ user.go | 36 +++++++-- 5 files changed, 258 insertions(+), 74 deletions(-) diff --git a/event.go b/event.go index bba396c..97cc00a 100644 --- a/event.go +++ b/event.go @@ -98,7 +98,9 @@ func (s *Session) addEventHandlerOnce(eventHandler EventHandler) func() { // AddHandler allows you to add an event handler that will be fired anytime // the Discord WSAPI event that matches the function fires. -// events.go contains all the Discord WSAPI events that can be fired. +// The first parameter is a *Session, and the second parameter is a pointer +// to a struct corresponding to the event for which you want to listen. +// // eg: // Session.AddHandler(func(s *discordgo.Session, m *discordgo.MessageCreate) { // }) @@ -106,6 +108,13 @@ func (s *Session) addEventHandlerOnce(eventHandler EventHandler) func() { // or: // Session.AddHandler(func(s *discordgo.Session, m *discordgo.PresenceUpdate) { // }) +// +// List of events can be found at this page, with corresponding names in the +// library for each event: https://discordapp.com/developers/docs/topics/gateway#event-names +// There are also synthetic events fired by the library internally which are +// available for handling, like Connect, Disconnect, and RateLimit. +// events.go contains all of the Discord WSAPI and synthetic events that can be handled. +// // The return value of this method is a function, that when called will remove the // event handler. func (s *Session) AddHandler(handler interface{}) func() { diff --git a/message.go b/message.go index 4fd468f..b67c01d 100644 --- a/message.go +++ b/message.go @@ -32,20 +32,53 @@ const ( // A Message stores all data related to a specific Discord message. type Message struct { - ID string `json:"id"` - ChannelID string `json:"channel_id"` - Content string `json:"content"` - Timestamp Timestamp `json:"timestamp"` - EditedTimestamp Timestamp `json:"edited_timestamp"` - MentionRoles []string `json:"mention_roles"` - Tts bool `json:"tts"` - MentionEveryone bool `json:"mention_everyone"` - Author *User `json:"author"` - Attachments []*MessageAttachment `json:"attachments"` - Embeds []*MessageEmbed `json:"embeds"` - Mentions []*User `json:"mentions"` - Reactions []*MessageReactions `json:"reactions"` - Type MessageType `json:"type"` + // The ID of the message. + ID string `json:"id"` + + // The ID of the channel in which the message was sent. + ChannelID string `json:"channel_id"` + + // The content of the message. + Content string `json:"content"` + + // The time at which the messsage was sent. + // CAUTION: this field may be removed in a + // future API version; it is safer to calculate + // the creation time via the ID. + Timestamp Timestamp `json:"timestamp"` + + // The time at which the last edit of the message + // occurred, if it has been edited. + EditedTimestamp Timestamp `json:"edited_timestamp"` + + // The roles mentioned in the message. + MentionRoles []string `json:"mention_roles"` + + // Whether the message is text-to-speech. + Tts bool `json:"tts"` + + // Whether the message mentions everyone. + MentionEveryone bool `json:"mention_everyone"` + + // The author of the message. This is not guaranteed to be a + // valid user (webhook-sent messages do not possess a full author). + Author *User `json:"author"` + + // A list of attachments present in the message. + Attachments []*MessageAttachment `json:"attachments"` + + // A list of embeds present in the message. Multiple + // embeds can currently only be sent by webhooks. + Embeds []*MessageEmbed `json:"embeds"` + + // A list of users mentioned in the message. + Mentions []*User `json:"mentions"` + + // A list of reactions to the message. + Reactions []*MessageReactions `json:"reactions"` + + // The type of the message. + Type MessageType `json:"type"` } // File stores info about files you e.g. send in messages. diff --git a/state.go b/state.go index 8158708..662814c 100644 --- a/state.go +++ b/state.go @@ -32,6 +32,7 @@ type State struct { sync.RWMutex Ready + // MaxMessageCount represents how many messages per channel the state will store. MaxMessageCount int TrackChannels bool TrackEmojis bool @@ -607,7 +608,7 @@ func (s *State) EmojisAdd(guildID string, emojis []*Emoji) error { // MessageAdd adds a message to the current world state, or updates it if it exists. // If the channel cannot be found, the message is discarded. -// Messages are kept in state up to s.MaxMessageCount +// Messages are kept in state up to s.MaxMessageCount per channel. func (s *State) MessageAdd(message *Message) error { if s == nil { return ErrNilState diff --git a/structs.go b/structs.go index aa52a1e..3e59aa5 100644 --- a/structs.go +++ b/structs.go @@ -193,19 +193,47 @@ const ( // A Channel holds all data related to an individual Discord channel. type Channel struct { - ID string `json:"id"` - GuildID string `json:"guild_id"` - Name string `json:"name"` - Topic string `json:"topic"` - Type ChannelType `json:"type"` - LastMessageID string `json:"last_message_id"` - NSFW bool `json:"nsfw"` - Position int `json:"position"` - Bitrate int `json:"bitrate"` - Recipients []*User `json:"recipients"` - Messages []*Message `json:"-"` + // The ID of the channel. + ID string `json:"id"` + + // The ID of the guild to which the channel belongs, if it is in a guild. + // Else, this ID is empty (e.g. DM channels). + GuildID string `json:"guild_id"` + + // The name of the channel. + Name string `json:"name"` + + // The topic of the channel. + Topic string `json:"topic"` + + // The type of the channel. + Type ChannelType `json:"type"` + + // The ID of the last message sent in the channel. This is not + // guaranteed to be an ID of a valid message. + LastMessageID string `json:"last_message_id"` + + // Whether the channel is marked as NSFW. + NSFW bool `json:"nsfw"` + + // The position of the channel, used for sorting in client. + Position int `json:"position"` + + // The bitrate of the channel, if it is a voice channel. + Bitrate int `json:"bitrate"` + + // The recipients of the channel. This is only populated in DM channels. + Recipients []*User `json:"recipients"` + + // The messages in the channel. This is only present in state-cached channels, + // and State.MaxMessageCount must be non-zero. + Messages []*Message `json:"-"` + + // A list of permission overwrites present for the channel. PermissionOverwrites []*PermissionOverwrite `json:"permission_overwrites"` - ParentID string `json:"parent_id"` + + // The ID of the parent channel, if the channel is under a category + ParentID string `json:"parent_id"` } // A ChannelEdit holds Channel Feild data for a channel edit. @@ -263,28 +291,89 @@ const ( // A Guild holds all data related to a specific Discord Guild. Guilds are also // sometimes referred to as Servers in the Discord client. type Guild struct { - ID string `json:"id"` - Name string `json:"name"` - Icon string `json:"icon"` - Region string `json:"region"` - AfkChannelID string `json:"afk_channel_id"` - EmbedChannelID string `json:"embed_channel_id"` - OwnerID string `json:"owner_id"` - JoinedAt Timestamp `json:"joined_at"` - Splash string `json:"splash"` - AfkTimeout int `json:"afk_timeout"` - MemberCount int `json:"member_count"` - VerificationLevel VerificationLevel `json:"verification_level"` - EmbedEnabled bool `json:"embed_enabled"` - Large bool `json:"large"` // ?? - DefaultMessageNotifications int `json:"default_message_notifications"` - Roles []*Role `json:"roles"` - Emojis []*Emoji `json:"emojis"` - Members []*Member `json:"members"` - Presences []*Presence `json:"presences"` - Channels []*Channel `json:"channels"` - VoiceStates []*VoiceState `json:"voice_states"` - Unavailable bool `json:"unavailable"` + // The ID of the guild. + ID string `json:"id"` + + // The name of the guild. (2–100 characters) + Name string `json:"name"` + + // The hash of the guild's icon. Use Session.GuildIcon + // to retrieve the icon itself. + Icon string `json:"icon"` + + // The voice region of the guild. + Region string `json:"region"` + + // The ID of the AFK voice channel. + AfkChannelID string `json:"afk_channel_id"` + + // The ID of the embed channel ID, used for embed widgets. + EmbedChannelID string `json:"embed_channel_id"` + + // The user ID of the owner of the guild. + OwnerID string `json:"owner_id"` + + // The time at which the current user joined the guild. + // This field is only present in GUILD_CREATE events and websocket + // update events, and thus is only present in state-cached guilds. + JoinedAt Timestamp `json:"joined_at"` + + // The hash of the guild's splash. + Splash string `json:"splash"` + + // The timeout, in seconds, before a user is considered AFK in voice. + AfkTimeout int `json:"afk_timeout"` + + // The number of members in the guild. + // This field is only present in GUILD_CREATE events and websocket + // update events, and thus is only present in state-cached guilds. + MemberCount int `json:"member_count"` + + // The verification level required for the guild. + VerificationLevel VerificationLevel `json:"verification_level"` + + // Whether the guild has embedding enabled. + EmbedEnabled bool `json:"embed_enabled"` + + // Whether the guild is considered large. This is + // determined by a member threshold in the identify packet, + // and is currently hard-coded at 250 members in the library. + Large bool `json:"large"` + + // The default message notification setting for the guild. + // 0 == all messages, 1 == mentions only. + DefaultMessageNotifications int `json:"default_message_notifications"` + + // A list of roles in the guild. + Roles []*Role `json:"roles"` + + // A list of the custom emojis present in the guild. + Emojis []*Emoji `json:"emojis"` + + // A list of the members in the guild. + // This field is only present in GUILD_CREATE events and websocket + // update events, and thus is only present in state-cached guilds. + Members []*Member `json:"members"` + + // A list of partial presence objects for members in the guild. + // This field is only present in GUILD_CREATE events and websocket + // update events, and thus is only present in state-cached guilds. + Presences []*Presence `json:"presences"` + + // A list of channels in the guild. + // This field is only present in GUILD_CREATE events and websocket + // update events, and thus is only present in state-cached guilds. + Channels []*Channel `json:"channels"` + + // A list of voice states for the guild. + // This field is only present in GUILD_CREATE events and websocket + // update events, and thus is only present in state-cached guilds. + VoiceStates []*VoiceState `json:"voice_states"` + + // Whether this guild is currently unavailable (most likely due to outage). + // This field is only present in GUILD_CREATE events and websocket + // update events, and thus is only present in state-cached guilds. + Unavailable bool `json:"unavailable"` } // A UserGuild holds a brief version of a Guild @@ -311,14 +400,32 @@ type GuildParams struct { // A Role stores information about Discord guild member roles. type Role struct { - ID string `json:"id"` - Name string `json:"name"` - Managed bool `json:"managed"` - Mentionable bool `json:"mentionable"` - Hoist bool `json:"hoist"` - Color int `json:"color"` - Position int `json:"position"` - Permissions int `json:"permissions"` + // The ID of the role. + ID string `json:"id"` + + // The name of the role. + Name string `json:"name"` + + // Whether this role is managed by an integration, and + // thus cannot be manually added to, or taken from, members. + Managed bool `json:"managed"` + + // Whether this role is mentionable. + Mentionable bool `json:"mentionable"` + + // Whether this role is hoisted (shows up separately in member list). + Hoist bool `json:"hoist"` + + // The hex color of this role. + Color int `json:"color"` + + // The position of this role in the guild's role hierarchy. + Position int `json:"position"` + + // The permissions of the role on the guild (doesn't include channel overrides). + // This is a combination of bit masks; the presence of a certain permission can + // be checked by performing a bitwise AND between this int and the permission. + Permissions int `json:"permissions"` } // Mention returns a string which mentions the role @@ -418,15 +525,29 @@ type Assets struct { SmallText string `json:"small_text,omitempty"` } -// A Member stores user information for Guild members. +// A Member stores user information for Guild members. A guild +// member represents a certain user's presence in a guild. type Member struct { - GuildID string `json:"guild_id"` - JoinedAt string `json:"joined_at"` - Nick string `json:"nick"` - Deaf bool `json:"deaf"` - Mute bool `json:"mute"` - User *User `json:"user"` - Roles []string `json:"roles"` + // The guild ID on which the member exists. + GuildID string `json:"guild_id"` + + // The time at which the member joined the guild, in ISO8601. + JoinedAt string `json:"joined_at"` + + // The nickname of the member, if they have one. + Nick string `json:"nick"` + + // Whether the member is deafened at a guild level. + Deaf bool `json:"deaf"` + + // Whether the member is muted at a guild level. + Mute bool `json:"mute"` + + // The underlying user on which the member is based. + User *User `json:"user"` + + // A list of IDs of the roles which are possessed by the member. + Roles []string `json:"roles"` } // A Settings stores data for a specific users Discord client settings. diff --git a/user.go b/user.go index 101b906..5de4a82 100644 --- a/user.go +++ b/user.go @@ -7,15 +7,35 @@ import ( // A User stores all data for an individual Discord user. type User struct { - ID string `json:"id"` - Email string `json:"email"` - Username string `json:"username"` - Avatar string `json:"avatar"` + // The ID of the user. + ID string `json:"id"` + + // The email of the user. This is only present when + // the application possesses the email scope for the user. + Email string `json:"email"` + + // The user's username. + Username string `json:"username"` + + // The hash of the user's avatar. Use Session.UserAvatar + // to retrieve the avatar itself. + Avatar string `json:"avatar"` + + // The discriminator of the user (4 numbers after name). Discriminator string `json:"discriminator"` - Token string `json:"token"` - Verified bool `json:"verified"` - MFAEnabled bool `json:"mfa_enabled"` - Bot bool `json:"bot"` + + // The token of the user. This is only present for + // the user represented by the current session. + Token string `json:"token"` + + // Whether the user's email is verified. + Verified bool `json:"verified"` + + // Whether the user has multi-factor authentication enabled. + MFAEnabled bool `json:"mfa_enabled"` + + // Whether the user is a bot. + Bot bool `json:"bot"` } // String returns a unique identifier of the form username#discriminator