From 8fcd0f3b6fadb0441491d8f874fc21cff8cb7302 Mon Sep 17 00:00:00 2001 From: Qais Patankar Date: Sun, 3 Jan 2021 18:57:06 +0000 Subject: [PATCH] Improve Markdown in transmitter docs (discord) (#1351) --- bridge/discord/transmitter/transmitter.go | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/bridge/discord/transmitter/transmitter.go b/bridge/discord/transmitter/transmitter.go index e6d52a98..ed277be7 100644 --- a/bridge/discord/transmitter/transmitter.go +++ b/bridge/discord/transmitter/transmitter.go @@ -2,6 +2,7 @@ // arbitrary webhook messages to Discord. // // The package provides the following functionality: +// // - Creating new webhooks, whenever necessary // - Loading webhooks that we have previously created // - Sending new messages @@ -43,9 +44,8 @@ var ErrWebhookNotFound = errors.New("webhook for this channel and message does n // ErrPermissionDenied is returned if the bot does not have permission to manage webhooks. // -// It's important to note that: -// - a bot can have both a guild-wide permission and a channel-specific permission to manage webhooks -// - even if a bot has permission to manage the guild's webhooks, there could be channel specific overrides +// Bots can be granted a guild-wide permission and channel-specific permissions to manage webhooks. +// Despite potentially having guild-wide permission, channel specific overrides could deny a bot's permission to manage webhooks. var ErrPermissionDenied = errors.New("missing 'Manage Webhooks' permission") // New returns a new Transmitter given a Discord session, guild ID, and title. @@ -62,9 +62,7 @@ func New(session *discordgo.Session, guild string, title string, autoCreate bool } } -// Send transmits a message to the given channel with the provided webhook data. -// -// Note that this function will wait until Discord responds with an answer. +// Send transmits a message to the given channel with the provided webhook data, and waits until Discord responds with message data. func (t *Transmitter) Send(channelID string, params *discordgo.WebhookParams) (*discordgo.Message, error) { wh, err := t.getOrCreateWebhook(channelID) if err != nil { @@ -124,16 +122,19 @@ func (t *Transmitter) AddWebhook(channelID string, webhook *discordgo.Webhook) b // RefreshGuildWebhooks loads "relevant" webhooks into the transmitter, with careful permission handling. // // Notes: +// // - A webhook is "relevant" if it was created by this bot -- the ApplicationID should match the bot's ID. // - The term "having permission" means having the "Manage Webhooks" permission. See ErrPermissionDenied for more information. // - This function is additive and will not unload previously loaded webhooks. // - A nil channelIDs slice is treated the same as an empty one. // // If the bot has guild-wide permission: +// // 1. it will load any "relevant" webhooks from the entire guild // 2. the given slice is ignored // // If the bot does not have guild-wide permission: +// // 1. it will load any "relevant" webhooks in each channel // 2. a single error will be returned if any error occurs (incl. if there is no permission for any of these channels) //