docs: Updating Inline Docs and API References

apps.go

@@ -19,11 +19,15 @@ type EventAuthorization struct {
 	IsEnterpriseInstall bool   `json:"is_enterprise_install"`
 }
 
+// ListEventAuthorizations lists authed users and teams for the given event_context.
+// You must provide an app-level token to the client using OptionAppLevelToken.
+// For more details, see ListEventAuthorizationsContext documentation.
 func (api *Client) ListEventAuthorizations(eventContext string) ([]EventAuthorization, error) {
 	return api.ListEventAuthorizationsContext(context.Background(), eventContext)
 }
 
-// ListEventAuthorizationsContext lists authed users and teams for the given event_context. You must provide an app-level token to the client using OptionAppLevelToken. More info: https://api.slack.com/methods/apps.event.authorizations.list
+// ListEventAuthorizationsContext lists authed users and teams for the given event_context with a custom context.
+// Slack API docs: https://api.slack.com/methods/apps.event.authorizations.list
 func (api *Client) ListEventAuthorizationsContext(ctx context.Context, eventContext string) ([]EventAuthorization, error) {
 	resp := &listEventAuthorizationsResponse{}
 
@@ -43,10 +47,14 @@ func (api *Client) ListEventAuthorizationsContext(ctx context.Context, eventCont
 	return resp.Authorizations, nil
 }
 
+// UninstallApp uninstalls your app from a workspace.
+// For more details, see UninstallAppContext documentation.
 func (api *Client) UninstallApp(clientID, clientSecret string) error {
 	return api.UninstallAppContext(context.Background(), clientID, clientSecret)
 }
 
+// UninstallAppContext uninstalls your app from a workspace with a custom context.
+// Slack API docs: https://api.slack.com/methods/apps.uninstall
 func (api *Client) UninstallAppContext(ctx context.Context, clientID, clientSecret string) error {
 	values := url.Values{
 		"client_id":     {clientID},

auth.go

@@ -22,12 +22,14 @@ func (api *Client) authRequest(ctx context.Context, path string, values url.Valu
 	return response, response.Err()
 }
 
-// SendAuthRevoke will send a revocation for our token
+// SendAuthRevoke will send a revocation for our token.
+// For more details, see SendAuthRevokeContext documentation.
 func (api *Client) SendAuthRevoke(token string) (*AuthRevokeResponse, error) {
 	return api.SendAuthRevokeContext(context.Background(), token)
 }
 
-// SendAuthRevokeContext will send a revocation request for our token to api.revoke with context
+// SendAuthRevokeContext will send a revocation request for our token to api.revoke with a custom context.
+// Slack API docs: https://api.slack.com/methods/auth.revoke
 func (api *Client) SendAuthRevokeContext(ctx context.Context, token string) (*AuthRevokeResponse, error) {
 	if token == "" {
 		token = api.token
@@ -50,12 +52,13 @@ type ListTeamsParameters struct {
 }
 
 // ListTeams returns all workspaces a token can access.
-// More info: https://api.slack.com/methods/admin.teams.list
+// For more details, see ListTeamsContext documentation.
 func (api *Client) ListTeams(params ListTeamsParameters) ([]Team, string, error) {
 	return api.ListTeamsContext(context.Background(), params)
 }
 
-// ListTeams returns all workspaces a token can access with a custom context.
+// ListTeamsContext returns all workspaces a token can access with a custom context.
+// Slack API docs: https://api.slack.com/methods/auth.teams.list
 func (api *Client) ListTeamsContext(ctx context.Context, params ListTeamsParameters) ([]Team, string, error) {
 	values := url.Values{
 		"token": {api.token},

bookmarks.go

@@ -55,12 +55,14 @@ type listBookmarksResponse struct {
 	SlackResponse
 }
 
-// AddBookmark adds a bookmark in a channel
+// AddBookmark adds a bookmark in a channel.
+// For more details, see AddBookmarkContext documentation.
 func (api *Client) AddBookmark(channelID string, params AddBookmarkParameters) (Bookmark, error) {
 	return api.AddBookmarkContext(context.Background(), channelID, params)
 }
 
-// AddBookmarkContext adds a bookmark in a channel with a custom context
+// AddBookmarkContext adds a bookmark in a channel with a custom context.
+// Slack API docs: https://api.slack.com/methods/bookmarks.add
 func (api *Client) AddBookmarkContext(ctx context.Context, channelID string, params AddBookmarkParameters) (Bookmark, error) {
 	values := url.Values{
 		"channel_id": {channelID},
@@ -89,12 +91,14 @@ func (api *Client) AddBookmarkContext(ctx context.Context, channelID string, par
 	return response.Bookmark, response.Err()
 }
 
-// RemoveBookmark removes a bookmark from a channel
+// RemoveBookmark removes a bookmark from a channel.
+// For more details, see RemoveBookmarkContext documentation.
 func (api *Client) RemoveBookmark(channelID, bookmarkID string) error {
 	return api.RemoveBookmarkContext(context.Background(), channelID, bookmarkID)
 }
 
-// RemoveBookmarkContext removes a bookmark from a channel with a custom context
+// RemoveBookmarkContext removes a bookmark from a channel with a custom context.
+// Slack API docs: https://api.slack.com/methods/bookmarks.remove
 func (api *Client) RemoveBookmarkContext(ctx context.Context, channelID, bookmarkID string) error {
 	values := url.Values{
 		"channel_id":  {channelID},
@@ -111,11 +115,13 @@ func (api *Client) RemoveBookmarkContext(ctx context.Context, channelID, bookmar
 }
 
 // ListBookmarks returns all bookmarks for a channel.
+// For more details, see ListBookmarksContext documentation.
 func (api *Client) ListBookmarks(channelID string) ([]Bookmark, error) {
 	return api.ListBookmarksContext(context.Background(), channelID)
 }
 
 // ListBookmarksContext returns all bookmarks for a channel with a custom context.
+// Slack API docs: https://api.slack.com/methods/bookmarks.edit
 func (api *Client) ListBookmarksContext(ctx context.Context, channelID string) ([]Bookmark, error) {
 	values := url.Values{
 		"channel_id": {channelID},
@@ -130,10 +136,14 @@ func (api *Client) ListBookmarksContext(ctx context.Context, channelID string) (
 	return response.Bookmarks, response.Err()
 }
 
+// EditBookmark edits a bookmark in a channel.
+// For more details, see EditBookmarkContext documentation.
 func (api *Client) EditBookmark(channelID, bookmarkID string, params EditBookmarkParameters) (Bookmark, error) {
 	return api.EditBookmarkContext(context.Background(), channelID, bookmarkID, params)
 }
 
+// EditBookmarkContext edits a bookmark in a channel with a custom context.
+// Slack API docs: https://api.slack.com/methods/bookmarks.edit
 func (api *Client) EditBookmarkContext(ctx context.Context, channelID, bookmarkID string, params EditBookmarkParameters) (Bookmark, error) {
 	values := url.Values{
 		"channel_id":  {channelID},

bots.go

@@ -40,12 +40,14 @@ type GetBotInfoParameters struct {
 	TeamID string
 }
 
-// GetBotInfo will retrieve the complete bot information
+// GetBotInfo will retrieve the complete bot information.
+// For more details, see GetBotInfoContext documentation.
 func (api *Client) GetBotInfo(parameters GetBotInfoParameters) (*Bot, error) {
 	return api.GetBotInfoContext(context.Background(), parameters)
 }
 
-// GetBotInfoContext will retrieve the complete bot information using a custom context
+// GetBotInfoContext will retrieve the complete bot information using a custom context.
+// Slack API docs: https://api.slack.com/methods/bots.info
 func (api *Client) GetBotInfoContext(ctx context.Context, parameters GetBotInfoParameters) (*Bot, error) {
 	values := url.Values{
 		"token": {api.token},

chat.go

@@ -37,7 +37,7 @@ type chatResponseFull struct {
 	SlackResponse
 }
 
-// getMessageTimestamp will inspect the `chatResponseFull` to ruturn a timestamp value
+// getMessageTimestamp will inspect the `chatResponseFull` to return a timestamp value
 // in `chat.postMessage` its under `ts`
 // in `chat.postEphemeral` its under `message_ts`
 func (c chatResponseFull) getMessageTimestamp() string {
@@ -88,12 +88,14 @@ func NewPostMessageParameters() PostMessageParameters {
 	}
 }
 
-// DeleteMessage deletes a message in a channel
+// DeleteMessage deletes a message in a channel.
+// For more details, see DeleteMessageContext documentation.
 func (api *Client) DeleteMessage(channel, messageTimestamp string) (string, string, error) {
 	return api.DeleteMessageContext(context.Background(), channel, messageTimestamp)
 }
 
-// DeleteMessageContext deletes a message in a channel with a custom context
+// DeleteMessageContext deletes a message in a channel with a custom context.
+// Slack API docs: https://api.slack.com/methods/chat.delete
 func (api *Client) DeleteMessageContext(ctx context.Context, channel, messageTimestamp string) (string, string, error) {
 	respChannel, respTimestamp, _, err := api.SendMessageContext(
 		ctx,
@@ -106,13 +108,13 @@ func (api *Client) DeleteMessageContext(ctx context.Context, channel, messageTim
 // ScheduleMessage sends a message to a channel.
 // Message is escaped by default according to https://api.slack.com/docs/formatting
 // Use http://davestevens.github.io/slack-message-builder/ to help crafting your message.
+// For more details, see ScheduleMessageContext documentation.
 func (api *Client) ScheduleMessage(channelID, postAt string, options ...MsgOption) (string, string, error) {
 	return api.ScheduleMessageContext(context.Background(), channelID, postAt, options...)
 }
 
-// ScheduleMessageContext sends a message to a channel with a custom context
-//
-// For more details, see ScheduleMessage documentation.
+// ScheduleMessageContext sends a message to a channel with a custom context.
+// Slack API docs: https://api.slack.com/methods/chat.scheduleMessage
 func (api *Client) ScheduleMessageContext(ctx context.Context, channelID, postAt string, options ...MsgOption) (string, string, error) {
 	respChannel, respTimestamp, _, err := api.SendMessageContext(
 		ctx,
@@ -126,12 +128,13 @@ func (api *Client) ScheduleMessageContext(ctx context.Context, channelID, postAt
 // PostMessage sends a message to a channel.
 // Message is escaped by default according to https://api.slack.com/docs/formatting
 // Use http://davestevens.github.io/slack-message-builder/ to help crafting your message.
+// For more details, see PostMessageContext documentation.
 func (api *Client) PostMessage(channelID string, options ...MsgOption) (string, string, error) {
 	return api.PostMessageContext(context.Background(), channelID, options...)
 }
 
-// PostMessageContext sends a message to a channel with a custom context
-// For more details, see PostMessage documentation.
+// PostMessageContext sends a message to a channel with a custom context.
+// Slack API docs: https://api.slack.com/methods/chat.postMessage
 func (api *Client) PostMessageContext(ctx context.Context, channelID string, options ...MsgOption) (string, string, error) {
 	respChannel, respTimestamp, _, err := api.SendMessageContext(
 		ctx,
@@ -145,12 +148,13 @@ func (api *Client) PostMessageContext(ctx context.Context, channelID string, opt
 // PostEphemeral sends an ephemeral message to a user in a channel.
 // Message is escaped by default according to https://api.slack.com/docs/formatting
 // Use http://davestevens.github.io/slack-message-builder/ to help crafting your message.
+// For more details, see PostEphemeralContext documentation.
 func (api *Client) PostEphemeral(channelID, userID string, options ...MsgOption) (string, error) {
 	return api.PostEphemeralContext(context.Background(), channelID, userID, options...)
 }
 
-// PostEphemeralContext sends an ephemeal message to a user in a channel with a custom context
-// For more details, see PostEphemeral documentation
+// PostEphemeralContext sends an ephemeral message to a user in a channel with a custom context.
+// Slack API docs: https://api.slack.com/methods/chat.postEphemeral
 func (api *Client) PostEphemeralContext(ctx context.Context, channelID, userID string, options ...MsgOption) (timestamp string, err error) {
 	_, timestamp, _, err = api.SendMessageContext(
 		ctx,
@@ -161,12 +165,14 @@ func (api *Client) PostEphemeralContext(ctx context.Context, channelID, userID s
 	return timestamp, err
 }
 
-// UpdateMessage updates a message in a channel
+// UpdateMessage updates a message in a channel.
+// For more details, see UpdateMessageContext documentation.
 func (api *Client) UpdateMessage(channelID, timestamp string, options ...MsgOption) (string, string, string, error) {
 	return api.UpdateMessageContext(context.Background(), channelID, timestamp, options...)
 }
 
-// UpdateMessageContext updates a message in a channel
+// UpdateMessageContext updates a message in a channel with a custom context.
+// Slack API docs: https://api.slack.com/methods/chat.update
 func (api *Client) UpdateMessageContext(ctx context.Context, channelID, timestamp string, options ...MsgOption) (string, string, string, error) {
 	return api.SendMessageContext(
 		ctx,
@@ -176,38 +182,38 @@ func (api *Client) UpdateMessageContext(ctx context.Context, channelID, timestam
 	)
 }
 
-// UnfurlMessage unfurls a message in a channel
+// UnfurlMessage unfurls a message in a channel.
+// For more details, see UnfurlMessageContext documentation.
 func (api *Client) UnfurlMessage(channelID, timestamp string, unfurls map[string]Attachment, options ...MsgOption) (string, string, string, error) {
 	return api.UnfurlMessageContext(context.Background(), channelID, timestamp, unfurls, options...)
 }
 
-// UnfurlMessageContext unfurls a message in a channel with a custom context
+// UnfurlMessageContext unfurls a message in a channel with a custom context.
+// Slack API docs: https://api.slack.com/methods/chat.unfurl
 func (api *Client) UnfurlMessageContext(ctx context.Context, channelID, timestamp string, unfurls map[string]Attachment, options ...MsgOption) (string, string, string, error) {
 	return api.SendMessageContext(ctx, channelID, MsgOptionUnfurl(timestamp, unfurls), MsgOptionCompose(options...))
 }
 
-// UnfurlMessageWithAuthURL sends an unfurl request containing an
-// authentication URL.
-// For more details see:
-// https://api.slack.com/reference/messaging/link-unfurling#authenticated_unfurls
+// UnfurlMessageWithAuthURL sends an unfurl request containing an authentication URL.
+// For more details, see UnfurlMessageWithAuthURLContext documentation.
 func (api *Client) UnfurlMessageWithAuthURL(channelID, timestamp string, userAuthURL string, options ...MsgOption) (string, string, string, error) {
 	return api.UnfurlMessageWithAuthURLContext(context.Background(), channelID, timestamp, userAuthURL, options...)
 }
 
-// UnfurlMessageWithAuthURLContext sends an unfurl request containing an
-// authentication URL.
-// For more details see:
-// https://api.slack.com/reference/messaging/link-unfurling#authenticated_unfurls
+// UnfurlMessageWithAuthURLContext sends an unfurl request containing an authentication URL with a custom context.
+// For more details see: https://api.slack.com/reference/messaging/link-unfurling#authenticated_unfurls
 func (api *Client) UnfurlMessageWithAuthURLContext(ctx context.Context, channelID, timestamp string, userAuthURL string, options ...MsgOption) (string, string, string, error) {
 	return api.SendMessageContext(ctx, channelID, MsgOptionUnfurlAuthURL(timestamp, userAuthURL), MsgOptionCompose(options...))
 }
 
 // SendMessage more flexible method for configuring messages.
+// For more details, see SendMessageContext documentation.
 func (api *Client) SendMessage(channel string, options ...MsgOption) (string, string, string, error) {
 	return api.SendMessageContext(context.Background(), channel, options...)
 }
 
 // SendMessageContext more flexible method for configuring messages with a custom context.
+// Slack API docs: https://api.slack.com/methods/chat.postMessage
 func (api *Client) SendMessageContext(ctx context.Context, channelID string, options ...MsgOption) (_channel string, _timestamp string, _text string, err error) {
 	var (
 		req      *http.Request
@@ -771,22 +777,21 @@ func MsgOptionPostMessageParameters(params PostMessageParameters) MsgOption {
 	}
 }
 
-// PermalinkParameters are the parameters required to get a permalink to a
-// message. Slack documentation can be found here:
-// https://api.slack.com/methods/chat.getPermalink
+// PermalinkParameters are the parameters required to get a permalink to a message.
 type PermalinkParameters struct {
 	Channel string
 	Ts      string
 }
 
-// GetPermalink returns the permalink for a message. It takes
-// PermalinkParameters and returns a string containing the permalink. It
-// returns an error if unable to retrieve the permalink.
+// GetPermalink returns the permalink for a message. It takes PermalinkParameters and returns a string containing the
+// permalink. It returns an error if unable to retrieve the permalink.
+// For more details, see GetPermalinkContext documentation.
 func (api *Client) GetPermalink(params *PermalinkParameters) (string, error) {
 	return api.GetPermalinkContext(context.Background(), params)
 }
 
 // GetPermalinkContext returns the permalink for a message using a custom context.
+// Slack API docs: https://api.slack.com/methods/chat.getPermalink
 func (api *Client) GetPermalinkContext(ctx context.Context, params *PermalinkParameters) (string, error) {
 	values := url.Values{
 		"channel":    {params.Channel},
@@ -814,12 +819,14 @@ type GetScheduledMessagesParameters struct {
 	Oldest  string
 }
 
-// GetScheduledMessages returns the list of scheduled messages based on params
+// GetScheduledMessages returns the list of scheduled messages based on params.
+// For more details, see GetScheduledMessagesContext documentation.
 func (api *Client) GetScheduledMessages(params *GetScheduledMessagesParameters) (channels []ScheduledMessage, nextCursor string, err error) {
 	return api.GetScheduledMessagesContext(context.Background(), params)
 }
 
-// GetScheduledMessagesContext returns the list of scheduled messages in a Slack team with a custom context
+// GetScheduledMessagesContext returns the list of scheduled messages based on params with a custom context.
+// Slack API docs: https://api.slack.com/methods/chat.getScheduledMessages.list
 func (api *Client) GetScheduledMessagesContext(ctx context.Context, params *GetScheduledMessagesParameters) (channels []ScheduledMessage, nextCursor string, err error) {
 	values := url.Values{
 		"token": {api.token},
@@ -862,12 +869,14 @@ type DeleteScheduledMessageParameters struct {
 	AsUser             bool
 }
 
-// DeleteScheduledMessage returns the list of scheduled messages based on params
+// DeleteScheduledMessage deletes a pending scheduled message.
+// For more details, see DeleteScheduledMessageContext documentation.
 func (api *Client) DeleteScheduledMessage(params *DeleteScheduledMessageParameters) (bool, error) {
 	return api.DeleteScheduledMessageContext(context.Background(), params)
 }
 
-// DeleteScheduledMessageContext returns the list of scheduled messages in a Slack team with a custom context
+// DeleteScheduledMessageContext deletes a pending scheduled message with a custom context.
+// Slack API docs: https://api.slack.com/methods/chat.deleteScheduledMessage
 func (api *Client) DeleteScheduledMessageContext(ctx context.Context, params *DeleteScheduledMessageParameters) (bool, error) {
 	values := url.Values{
 		"token":                {api.token},