docs: add godoc for exported names

cmd/terramate/cli/telemetry/record.go

@@ -4,23 +4,28 @@
 package telemetry
 
 import (
+	"errors"
 	"runtime"
 	"slices"
 	"sync"
 )
 
+// Record is used to aggregate telemetry data over the runtime of the application.
 type Record struct {
 	sync.Mutex
 	msg  *Message
 	done <-chan error
 }
 
+// NewRecord creates an empty record.
 func NewRecord() *Record {
 	return &Record{
 		msg: &Message{},
 	}
 }
 
+// Set updates the telemetry data in the record.
+// It is safe to be called concurrently.
 func (r *Record) Set(opts ...MessageOpt) {
 	r.Lock()
 	defer r.Unlock()
@@ -35,20 +40,24 @@ func (r *Record) Set(opts ...MessageOpt) {
 	}
 }
 
+// MessageOpt is the option type for Set.
 type MessageOpt func(msg *Message)
 
+// Command sets the command name.
 func Command(cmd string) MessageOpt {
 	return func(msg *Message) {
 		msg.Command = cmd
 	}
 }
 
+// Command sets the organization name.
 func OrgName(orgName string) MessageOpt {
 	return func(msg *Message) {
 		msg.OrgName = orgName
 	}
 }
 
+// DetectFromEnv detects platform, auth type, signature, architecture and OS from the environment.
 func DetectFromEnv(credfile, cpsigfile, anasigfile string) MessageOpt {
 	return func(msg *Message) {
 		msg.Platform = DetectPlatformFromEnv()
@@ -61,6 +70,8 @@ func DetectFromEnv(credfile, cpsigfile, anasigfile string) MessageOpt {
 	}
 }
 
+// BoolFlag sets the given detail name if flag is true.
+// If ifCmds is not empty, the current command of the record must also match any of the given values.
 func BoolFlag(name string, flag bool, ifCmds ...string) MessageOpt {
 	return func(msg *Message) {
 		if flag {
@@ -75,10 +86,14 @@ func BoolFlag(name string, flag bool, ifCmds ...string) MessageOpt {
 	}
 }
 
+// StringFlag calls BoolFlag with flag = (stringFlag != "").
 func StringFlag(name string, flag string, ifCmds ...string) MessageOpt {
 	return BoolFlag(name, flag != "", ifCmds...)
 }
 
+// Send sends a message for the current record state asynchronously.
+// A record can only be sent once, subsequent calls will be ignored.
+// The function is non-blocking, the result can be checked with WaitForSend().
 func (r *Record) Send(params SendMessageParams) {
 	r.Lock()
 	defer r.Unlock()
@@ -88,12 +103,14 @@ func (r *Record) Send(params SendMessageParams) {
 	}
 }
 
+// WaitForSend waits until Send is done, either successfully, or with error/timeout.
 func (r *Record) WaitForSend() error {
 	if r.done == nil {
-		return nil
+		return errors.New("message was not sent")
 	}
 
 	return <-r.done
 }
 
+// DefaultRecord is the global default record.
 var DefaultRecord = NewRecord()

cmd/terramate/cli/telemetry/telemetry.go

@@ -20,6 +20,7 @@ import (
 	"github.com/terramate-io/terramate"
 )
 
+// PlatformType is the CI/CD platform.
 type PlatformType int
 
 const (
@@ -29,6 +30,7 @@ const (
 	PlatformGenericCI
 )
 
+// AuthType is the authentication method that was used.
 type AuthType int
 
 const (
@@ -40,6 +42,7 @@ const (
 	AuthAPIKey
 )
 
+// Message is the analytics data that will be collected.
 type Message struct {
 	Platform PlatformType `json:"platform,omitempty"`
 	Auth     AuthType     `json:"auth,omitempty"`
@@ -57,6 +60,7 @@ type Message struct {
 	Details []string `json:"details,omitempty"`
 }
 
+// DetectPlatformFromEnv detects PlatformType based on environment variables.
 func DetectPlatformFromEnv() PlatformType {
 	if isEnvVarSet("GITHUB_ACTIONS") {
 		return PlatformGithub
@@ -69,6 +73,7 @@ func DetectPlatformFromEnv() PlatformType {
 	}
 }
 
+// DetectPlatformFromEnv detects AuthType based on environment variables and credentials.
 func DetectAuthTypeFromEnv(credpath string) AuthType {
 	if isEnvVarSet("ACTIONS_ID_TOKEN_REQUEST_TOKEN") {
 		return AuthOIDCGithub
@@ -79,6 +84,7 @@ func DetectAuthTypeFromEnv(credpath string) AuthType {
 	}
 }
 
+// ReadSignature parses a signature file. It works for checkpoint and analytics signatures as both use the same format.
 func ReadSignature(p string) string {
 	sigBytes, err := os.ReadFile(p)
 	if err == nil {
@@ -90,6 +96,8 @@ func ReadSignature(p string) string {
 	return ""
 }
 
+// GenerateOrReadSignature attempts to read the analytics signature.
+// If not present, it will create a new one.
 func GenerateOrReadSignature(cpsigfile, anasigfile string) (string, bool) {
 	logger := log.With().
 		Str("action", "GenerateOrReadSignature()").
@@ -120,6 +128,7 @@ func GenerateOrReadSignature(cpsigfile, anasigfile string) (string, bool) {
 	return newsig, true
 }
 
+// GenerateSignature generates a new random signature.
 func GenerateSignature() string {
 	buf := make([]byte, 16)
 	_, _ = rand.Read(buf)
@@ -155,18 +164,21 @@ func getAuthProviderFromCredentials(credfile string) AuthType {
 	case "GitHub":
 		return AuthIDPGithub
 	default:
-		// There could be room here for AuthInvalid or AuthUnknown here.
+		// Not handling cases like unknown or invalid values.
 		return AuthNone
 	}
 }
 
+// SendMessageParams contains parameters for SendMessage.
 type SendMessageParams struct {
 	Endpoint *url.URL
 	Client   *http.Client
 	Version  string
 	Timeout  time.Duration
 }
 
+// SendMessage sends an analytics message to the backend endpoint asynchronously.
+// It returns a channel that will receive the result of the operation when it's done.
 func SendMessage(msg *Message, p SendMessageParams) <-chan error {
 	if p.Endpoint == nil {
 		url := Endpoint()