pothtonswer/discordmuffin
1
0
Fork 1
Code Issues 2 Pull requests 1 Projects 2 Releases Packages Wiki Activity Actions

Merge pull request #516 from CarsonHoffman/doc-improvements

Browse source 
General documentation improvements
This commit is contained in:
Bruce 2018-03-14 15:35:55 -05:00 committed by GitHub
commit 0840d4bc38
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 258 additions and 74 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
event.go
View file

@ -98,7 +98,9 @@ func (s *Session) addEventHandlerOnce(eventHandler EventHandler) func() {
// AddHandler allows you to add an event handler that will be fired anytime // AddHandler allows you to add an event handler that will be fired anytime
// the Discord WSAPI event that matches the function fires. // 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: // eg:
// Session.AddHandler(func(s *discordgo.Session, m *discordgo.MessageCreate) { // Session.AddHandler(func(s *discordgo.Session, m *discordgo.MessageCreate) {
// }) // })
@ -106,6 +108,13 @@ func (s *Session) addEventHandlerOnce(eventHandler EventHandler) func() {
// or: // or:
// Session.AddHandler(func(s *discordgo.Session, m *discordgo.PresenceUpdate) { // 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 // The return value of this method is a function, that when called will remove the
// event handler. // event handler.
func (s *Session) AddHandler(handler interface{}) func() { func (s *Session) AddHandler(handler interface{}) func() {

61
message.go
View file

@ -32,20 +32,53 @@ const (
// A Message stores all data related to a specific Discord message. // A Message stores all data related to a specific Discord message.
type Message struct { type Message struct {
ID string `json:"id"` // The ID of the message.
ChannelID string `json:"channel_id"` ID string `json:"id"`
Content string `json:"content"`
Timestamp Timestamp `json:"timestamp"` // The ID of the channel in which the message was sent.
EditedTimestamp Timestamp `json:"edited_timestamp"` ChannelID string `json:"channel_id"`
MentionRoles []string `json:"mention_roles"`
Tts bool `json:"tts"` // The content of the message.
MentionEveryone bool `json:"mention_everyone"` Content string `json:"content"`
Author *User `json:"author"`
Attachments []*MessageAttachment `json:"attachments"` // The time at which the messsage was sent.
Embeds []*MessageEmbed `json:"embeds"` // CAUTION: this field may be removed in a
Mentions []*User `json:"mentions"` // future API version; it is safer to calculate
Reactions []*MessageReactions `json:"reactions"` // the creation time via the ID.
Type MessageType `json:"type"` 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. // File stores info about files you e.g. send in messages.

3
state.go
View file

@ -32,6 +32,7 @@ type State struct {
sync.RWMutex sync.RWMutex
Ready Ready
// MaxMessageCount represents how many messages per channel the state will store.
MaxMessageCount int MaxMessageCount int
TrackChannels bool TrackChannels bool
TrackEmojis 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. // 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. // 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 { func (s *State) MessageAdd(message *Message) error {
if s == nil { if s == nil {
return ErrNilState return ErrNilState

221
structs.go
View file

@ -193,19 +193,47 @@ const (
// A Channel holds all data related to an individual Discord channel. // A Channel holds all data related to an individual Discord channel.
type Channel struct { type Channel struct {
ID string `json:"id"` // The ID of the channel.
GuildID string `json:"guild_id"` ID string `json:"id"`
Name string `json:"name"`
Topic string `json:"topic"` // The ID of the guild to which the channel belongs, if it is in a guild.
Type ChannelType `json:"type"` // Else, this ID is empty (e.g. DM channels).
LastMessageID string `json:"last_message_id"` GuildID string `json:"guild_id"`
NSFW bool `json:"nsfw"`
Position int `json:"position"` // The name of the channel.
Bitrate int `json:"bitrate"` Name string `json:"name"`
Recipients []*User `json:"recipients"`
Messages []*Message `json:"-"` // 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"` 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. // 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 // A Guild holds all data related to a specific Discord Guild. Guilds are also
// sometimes referred to as Servers in the Discord client. // sometimes referred to as Servers in the Discord client.
type Guild struct { type Guild struct {
ID string `json:"id"` // The ID of the guild.
Name string `json:"name"` ID string `json:"id"`
Icon string `json:"icon"`
Region string `json:"region"` // The name of the guild. (2–100 characters)
AfkChannelID string `json:"afk_channel_id"` Name string `json:"name"`
EmbedChannelID string `json:"embed_channel_id"`
OwnerID string `json:"owner_id"` // The hash of the guild's icon. Use Session.GuildIcon
JoinedAt Timestamp `json:"joined_at"` // to retrieve the icon itself.
Splash string `json:"splash"` Icon string `json:"icon"`
AfkTimeout int `json:"afk_timeout"`
MemberCount int `json:"member_count"` // The voice region of the guild.
VerificationLevel VerificationLevel `json:"verification_level"` Region string `json:"region"`
EmbedEnabled bool `json:"embed_enabled"`
Large bool `json:"large"` // ?? // The ID of the AFK voice channel.
DefaultMessageNotifications int `json:"default_message_notifications"` AfkChannelID string `json:"afk_channel_id"`
Roles []*Role `json:"roles"`
Emojis []*Emoji `json:"emojis"` // The ID of the embed channel ID, used for embed widgets.
Members []*Member `json:"members"` EmbedChannelID string `json:"embed_channel_id"`
Presences []*Presence `json:"presences"`
Channels []*Channel `json:"channels"` // The user ID of the owner of the guild.
VoiceStates []*VoiceState `json:"voice_states"` OwnerID string `json:"owner_id"`
Unavailable bool `json:"unavailable"`
// 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 // 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. // A Role stores information about Discord guild member roles.
type Role struct { type Role struct {
ID string `json:"id"` // The ID of the role.
Name string `json:"name"` ID string `json:"id"`
Managed bool `json:"managed"`
Mentionable bool `json:"mentionable"` // The name of the role.
Hoist bool `json:"hoist"` Name string `json:"name"`
Color int `json:"color"`
Position int `json:"position"` // Whether this role is managed by an integration, and
Permissions int `json:"permissions"` // 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 // Mention returns a string which mentions the role
@ -418,15 +525,29 @@ type Assets struct {
SmallText string `json:"small_text,omitempty"` 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 { type Member struct {
GuildID string `json:"guild_id"` // The guild ID on which the member exists.
JoinedAt string `json:"joined_at"` GuildID string `json:"guild_id"`
Nick string `json:"nick"`
Deaf bool `json:"deaf"` // The time at which the member joined the guild, in ISO8601.
Mute bool `json:"mute"` JoinedAt string `json:"joined_at"`
User *User `json:"user"`
Roles []string `json:"roles"` // 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. // A Settings stores data for a specific users Discord client settings.

36
user.go
View file

@ -7,15 +7,35 @@ import (
// A User stores all data for an individual Discord user. // A User stores all data for an individual Discord user.
type User struct { type User struct {
ID string `json:"id"` // The ID of the user.
Email string `json:"email"` ID string `json:"id"`
Username string `json:"username"`
Avatar string `json:"avatar"` // 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"` Discriminator string `json:"discriminator"`
Token string `json:"token"`
Verified bool `json:"verified"` // The token of the user. This is only present for
MFAEnabled bool `json:"mfa_enabled"` // the user represented by the current session.
Bot bool `json:"bot"` 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 // String returns a unique identifier of the form username#discriminator