From fb8e79cfecf97ceb60b0c311ea350141ccba67a2 Mon Sep 17 00:00:00 2001 From: Adam Chalkley Date: Tue, 21 Nov 2023 06:18:27 -0600 Subject: [PATCH] Update Go Doc comment formatting - use bullet lists for collections of URLs - add whitespace to help separate URLs (where needed) - use link references More opportunities for cleanup remain. --- adaptivecard/adaptivecard.go | 27 +++++++++++++-------------- adaptivecard/doc.go | 28 ++++++++++++++-------------- adaptivecard/format.go | 12 ++++++------ messagecard.go | 8 +++++--- messagecard/doc.go | 4 ++-- messagecard/format.go | 9 +++++---- messagecard/messagecard.go | 10 ++++++---- 7 files changed, 51 insertions(+), 47 deletions(-) diff --git a/adaptivecard/adaptivecard.go b/adaptivecard/adaptivecard.go index 4ab6efc..3d32d70 100644 --- a/adaptivecard/adaptivecard.go +++ b/adaptivecard/adaptivecard.go @@ -70,10 +70,10 @@ const ( // Attachment constants. // -// https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference -// https://docs.microsoft.com/en-us/dotnet/api/microsoft.bot.schema.attachmentlayouttypes -// https://docs.microsoft.com/en-us/javascript/api/botframework-schema/attachmentlayouttypes -// https://github.com/matthidinger/ContosoScubaBot/blob/master/Cards/1-Schools.JSON +// - https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference +// - https://docs.microsoft.com/en-us/dotnet/api/microsoft.bot.schema.attachmentlayouttypes +// - https://docs.microsoft.com/en-us/javascript/api/botframework-schema/attachmentlayouttypes +// - https://github.com/matthidinger/ContosoScubaBot/blob/master/Cards/1-Schools.JSON const ( // AttachmentContentType is the supported type value for an attached @@ -291,12 +291,11 @@ const ( // Valid types for an Adaptive Card element. Not all types are supported by // Microsoft Teams. // -// https://adaptivecards.io/explorer/AdaptiveCard.html -// // TODO: Confirm whether all types are supported. // -// https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference#support-for-adaptive-cards -// https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/universal-action-model#schema +// - https://adaptivecards.io/explorer/AdaptiveCard.html +// - https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference#support-for-adaptive-cards +// - https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/universal-action-model#schema const ( TypeElementActionSet string = "ActionSet" TypeElementColumnSet string = "ColumnSet" @@ -736,9 +735,9 @@ type Actions []Action // Action represents an action that a user may take on a card. Actions // typically get rendered in an "action bar" at the bottom of a card. // -// https://adaptivecards.io/explorer/ActionSet.html -// https://adaptivecards.io/explorer/AdaptiveCard.html -// https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference +// - https://adaptivecards.io/explorer/ActionSet.html +// - https://adaptivecards.io/explorer/AdaptiveCard.html +// - https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference // // TODO: Extend with additional supported fields. type Action struct { @@ -784,9 +783,9 @@ type Action struct { // type (e.g., Column, ColumnSet, Container) is tapped or selected. // Action.ShowCard is not supported. // -// https://adaptivecards.io/explorer/Container.html -// https://adaptivecards.io/explorer/ColumnSet.html -// https://adaptivecards.io/explorer/Column.html +// - https://adaptivecards.io/explorer/Container.html +// - https://adaptivecards.io/explorer/ColumnSet.html +// - https://adaptivecards.io/explorer/Column.html // // TODO: Extend with additional supported fields. type ISelectAction struct { diff --git a/adaptivecard/doc.go b/adaptivecard/doc.go index 926d32a..1ad6ee1 100644 --- a/adaptivecard/doc.go +++ b/adaptivecard/doc.go @@ -13,19 +13,19 @@ See the provided examples in this repo, the Godoc generated documentation at https://pkg.go.dev/github.com/atc0005/go-teams-notify/v2 and the following resources for more information: -https://adaptivecards.io/explorer -https://docs.microsoft.com/en-us/adaptive-cards/ -https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/getting-started -https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/text-features -https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/universal-action-model -https://docs.microsoft.com/en-us/adaptive-cards/getting-started/bots -https://docs.microsoft.com/en-us/adaptive-cards/resources/principles -https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format -https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format#mention-support-within-adaptive-cards -https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference#support-for-adaptive-cards -https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/what-are-cards -https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using -https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using#send-adaptive-cards-using-an-incoming-webhook -https://stackoverflow.com/questions/50753072/microsoft-teams-webhook-generating-400-for-adaptive-card + - https://adaptivecards.io/explorer + - https://docs.microsoft.com/en-us/adaptive-cards/ + - https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/getting-started + - https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/text-features + - https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/universal-action-model + - https://docs.microsoft.com/en-us/adaptive-cards/getting-started/bots + - https://docs.microsoft.com/en-us/adaptive-cards/resources/principles + - https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format + - https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format#mention-support-within-adaptive-cards + - https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference#support-for-adaptive-cards + - https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/what-are-cards + - https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using + - https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using#send-adaptive-cards-using-an-incoming-webhook + - https://stackoverflow.com/questions/50753072/microsoft-teams-webhook-generating-400-for-adaptive-card */ package adaptivecard diff --git a/adaptivecard/format.go b/adaptivecard/format.go index 0b5818f..2a8c696 100644 --- a/adaptivecard/format.go +++ b/adaptivecard/format.go @@ -9,8 +9,8 @@ package adaptivecard import "strings" -// https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format#newlines-for-adaptive-cards -// https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/text-features +// - https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format#newlines-for-adaptive-cards +// - https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/text-features // Newline and break statement patterns stripped out of text content sent to // Microsoft Teams (by request). @@ -42,8 +42,8 @@ const ( // text in desktop, web and mobile, so even with using this helper function // some differences are to be expected. // -// https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format#newlines-for-adaptive-cards -// https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/text-features +// - https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format#newlines-for-adaptive-cards +// - https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/text-features func ConvertEOL(s string) string { s = strings.ReplaceAll(s, windowsEOLEscaped, unixEOLActual+unixEOLActual) s = strings.ReplaceAll(s, windowsEOLActual, unixEOLActual+unixEOLActual) @@ -66,8 +66,8 @@ func ConvertEOL(s string) string { // MessageCard format supports
statements for text spacing/formatting // where the Adaptive Card format does not. // -// https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format#newlines-for-adaptive-cards -// https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/text-features +// - https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format#newlines-for-adaptive-cards +// - https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/text-features func ConvertBreakToEOL(s string) string { return strings.ReplaceAll(s, breakStatement, unixEOLActual+unixEOLActual) } diff --git a/messagecard.go b/messagecard.go index dcabd19..52e0feb 100644 --- a/messagecard.go +++ b/messagecard.go @@ -75,6 +75,7 @@ const ( // PotentialActionMaxSupported is the maximum number of actions allowed in a // MessageCardPotentialAction collection. +// // https://docs.microsoft.com/en-us/outlook/actionable-messages/message-card-reference#actions // // Deprecated: use messagecard.PotentialActionMaxSupported instead. @@ -88,11 +89,12 @@ const PotentialActionMaxSupported = 4 var ErrPotentialActionsLimitReached = errors.New("potential actions collection limit reached") // MessageCardPotentialAction represents potential actions an user can do in a -// message card. See -// https://docs.microsoft.com/en-us/outlook/actionable-messages/message-card-reference#actions -// for more information. +// message card. See [Legacy actionable message card reference > Actions] for +// more information. // // Deprecated: use messagecard.PotentialAction instead. +// +// [Legacy actionable message card reference > Actions]: https://docs.microsoft.com/en-us/outlook/actionable-messages/message-card-reference#actions type MessageCardPotentialAction struct { // Type of the potential action. Can be OpenUri, HttpPOST, ActionCard or // InvokeAddInCommand. diff --git a/messagecard/doc.go b/messagecard/doc.go index 2ef83e9..b5bedb6 100644 --- a/messagecard/doc.go +++ b/messagecard/doc.go @@ -13,7 +13,7 @@ See the provided examples in this repo, the Godoc generated documentation at https://pkg.go.dev/github.com/atc0005/go-teams-notify/v2 and the following resources for more information: -https://docs.microsoft.com/en-us/outlook/actionable-messages/message-card-reference -https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using + - https://docs.microsoft.com/en-us/outlook/actionable-messages/message-card-reference + - https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using */ package messagecard diff --git a/messagecard/format.go b/messagecard/format.go index 029435b..24cd9cf 100644 --- a/messagecard/format.go +++ b/messagecard/format.go @@ -36,10 +36,11 @@ const ( ) // Even though Microsoft Teams doesn't show the additional newlines, -// https://messagecardplayground.azurewebsites.net/ DOES show the results -// as a formatted code block. Including the newlines now is an attempt at -// "future proofing" the codeblock support in MessageCard values sent to -// Microsoft Teams. +// [MessageCard Playground] DOES show the results as a formatted code block. +// Including the newlines now is an attempt at "future proofing" the codeblock +// support in MessageCard values sent to Microsoft Teams. +// +// [MessageCard Playground]: https://messagecardplayground.azurewebsites.net/ const ( // msTeamsCodeBlockSubmissionPrefix is the prefix appended to text input diff --git a/messagecard/messagecard.go b/messagecard/messagecard.go index bce099e..7a61243 100644 --- a/messagecard/messagecard.go +++ b/messagecard/messagecard.go @@ -49,6 +49,7 @@ const ( // PotentialActionMaxSupported is the maximum number of actions allowed in a // PotentialAction collection. +// // https://docs.microsoft.com/en-us/outlook/actionable-messages/message-card-reference#actions const PotentialActionMaxSupported = 4 @@ -57,10 +58,11 @@ const PotentialActionMaxSupported = 4 // MessageCard or a Section. var ErrPotentialActionsLimitReached = errors.New("potential actions collection limit reached") -// PotentialAction represents potential actions an user can do in a -// message card. See -// https://docs.microsoft.com/en-us/outlook/actionable-messages/message-card-reference#actions -// for more information. +// PotentialAction represents potential actions an user can do in a message +// card. See [Legacy actionable message card reference > Actions] for more +// information. +// +// [Legacy actionable message card reference > Actions]: https://docs.microsoft.com/en-us/outlook/actionable-messages/message-card-reference#actions type PotentialAction struct { // Type of the potential action. Can be OpenUri, HttpPOST, ActionCard or // InvokeAddInCommand.