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

@@ -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 {

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

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 <br> 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)
 }

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.

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

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

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.