From 65fcba95d9df439d6c08bb9248d942758d0b9dc7 Mon Sep 17 00:00:00 2001
From: Kynan Ware <47394200+BagToad@users.noreply.github.com>
Date: Wed, 4 Mar 2026 16:08:04 -0700
Subject: [PATCH] Add godoc comments to exported symbols in pkg/cmd/auth

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 pkg/cmd/auth/auth.go                                     | 1 +
 pkg/cmd/auth/gitcredential/helper.go                     | 2 ++
 pkg/cmd/auth/login/login.go                              | 2 ++
 pkg/cmd/auth/logout/logout.go                            | 2 ++
 pkg/cmd/auth/refresh/refresh.go                          | 2 ++
 pkg/cmd/auth/setupgit/setupgit.go                        | 2 ++
 pkg/cmd/auth/shared/contract/helper_config.go            | 1 +
 pkg/cmd/auth/shared/git_credential.go                    | 6 ++++++
 pkg/cmd/auth/shared/gitcredentials/fake_helper_config.go | 1 +
 pkg/cmd/auth/shared/login_flow.go                        | 3 +++
 pkg/cmd/auth/shared/oauth_scopes.go                      | 2 ++
 pkg/cmd/auth/shared/prompt.go                            | 1 +
 pkg/cmd/auth/shared/writeable.go                         | 1 +
 pkg/cmd/auth/status/status.go                            | 4 ++++
 pkg/cmd/auth/switch/switch.go                            | 2 ++
 pkg/cmd/auth/token/token.go                              | 2 ++
 16 files changed, 34 insertions(+)

diff --git a/pkg/cmd/auth/auth.go b/pkg/cmd/auth/auth.go
index 70e01653f..0200103a3 100644
--- a/pkg/cmd/auth/auth.go
+++ b/pkg/cmd/auth/auth.go
@@ -13,6 +13,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// NewCmdAuth creates the 'auth' command and its subcommands for managing GitHub authentication.
 func NewCmdAuth(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "auth <command>",
diff --git a/pkg/cmd/auth/gitcredential/helper.go b/pkg/cmd/auth/gitcredential/helper.go
index 9b64f74b9..0b06d3628 100644
--- a/pkg/cmd/auth/gitcredential/helper.go
+++ b/pkg/cmd/auth/gitcredential/helper.go
@@ -18,6 +18,7 @@ type config interface {
 	ActiveUser(string) (string, error)
 }
 
+// CredentialOptions holds the configuration for the git credential helper command.
 type CredentialOptions struct {
 	IO     *iostreams.IOStreams
 	Config func() (config, error)
@@ -25,6 +26,7 @@ type CredentialOptions struct {
 	Operation string
 }
 
+// NewCmdCredential creates the 'auth git-credential' command used as a git credential helper.
 func NewCmdCredential(f *cmdutil.Factory, runF func(*CredentialOptions) error) *cobra.Command {
 	opts := &CredentialOptions{
 		IO: f.IOStreams,
diff --git a/pkg/cmd/auth/login/login.go b/pkg/cmd/auth/login/login.go
index 88bc09f63..4d49a32c1 100644
--- a/pkg/cmd/auth/login/login.go
+++ b/pkg/cmd/auth/login/login.go
@@ -19,6 +19,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// LoginOptions holds the configuration and dependencies for the login command.
 type LoginOptions struct {
 	IO              *iostreams.IOStreams
 	Config          func() (gh.Config, error)
@@ -42,6 +43,7 @@ type LoginOptions struct {
 	Clipboard        bool
 }
 
+// NewCmdLogin creates the 'auth login' command for authenticating with a GitHub host.
 func NewCmdLogin(f *cmdutil.Factory, runF func(*LoginOptions) error) *cobra.Command {
 	opts := &LoginOptions{
 		IO:              f.IOStreams,
diff --git a/pkg/cmd/auth/logout/logout.go b/pkg/cmd/auth/logout/logout.go
index dd908a62d..95dd72f4d 100644
--- a/pkg/cmd/auth/logout/logout.go
+++ b/pkg/cmd/auth/logout/logout.go
@@ -13,6 +13,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// LogoutOptions holds the configuration and dependencies for the logout command.
 type LogoutOptions struct {
 	IO       *iostreams.IOStreams
 	Config   func() (gh.Config, error)
@@ -21,6 +22,7 @@ type LogoutOptions struct {
 	Username string
 }
 
+// NewCmdLogout creates the 'auth logout' command for removing authentication for a GitHub host.
 func NewCmdLogout(f *cmdutil.Factory, runF func(*LogoutOptions) error) *cobra.Command {
 	opts := &LogoutOptions{
 		IO:       f.IOStreams,
diff --git a/pkg/cmd/auth/refresh/refresh.go b/pkg/cmd/auth/refresh/refresh.go
index c025df465..84fb7908c 100644
--- a/pkg/cmd/auth/refresh/refresh.go
+++ b/pkg/cmd/auth/refresh/refresh.go
@@ -20,6 +20,7 @@ import (
 type token string
 type username string
 
+// RefreshOptions holds the configuration and dependencies for the refresh command.
 type RefreshOptions struct {
 	IO              *iostreams.IOStreams
 	Config          func() (gh.Config, error)
@@ -40,6 +41,7 @@ type RefreshOptions struct {
 	Clipboard       bool
 }
 
+// NewCmdRefresh creates the 'auth refresh' command for refreshing stored authentication credentials.
 func NewCmdRefresh(f *cmdutil.Factory, runF func(*RefreshOptions) error) *cobra.Command {
 	opts := &RefreshOptions{
 		IO:     f.IOStreams,
diff --git a/pkg/cmd/auth/setupgit/setupgit.go b/pkg/cmd/auth/setupgit/setupgit.go
index 0ff7b6903..d8d066670 100644
--- a/pkg/cmd/auth/setupgit/setupgit.go
+++ b/pkg/cmd/auth/setupgit/setupgit.go
@@ -16,6 +16,7 @@ type gitCredentialsConfigurer interface {
 	ConfigureOurs(hostname string) error
 }
 
+// SetupGitOptions holds the configuration and dependencies for the setup-git command.
 type SetupGitOptions struct {
 	IO                      *iostreams.IOStreams
 	Config                  func() (gh.Config, error)
@@ -24,6 +25,7 @@ type SetupGitOptions struct {
 	CredentialsHelperConfig gitCredentialsConfigurer
 }
 
+// NewCmdSetupGit creates the 'auth setup-git' command for configuring git to use GitHub CLI as a credential helper.
 func NewCmdSetupGit(f *cmdutil.Factory, runF func(*SetupGitOptions) error) *cobra.Command {
 	opts := &SetupGitOptions{
 		IO:     f.IOStreams,
diff --git a/pkg/cmd/auth/shared/contract/helper_config.go b/pkg/cmd/auth/shared/contract/helper_config.go
index d507e1091..ec7ae094d 100644
--- a/pkg/cmd/auth/shared/contract/helper_config.go
+++ b/pkg/cmd/auth/shared/contract/helper_config.go
@@ -17,6 +17,7 @@ type HelperConfig struct {
 	ConfigureHelper func(t *testing.T, hostname string)
 }
 
+// Test runs the contract tests to verify a HelperConfig implementation conforms to expected behavior.
 func (contract HelperConfig) Test(t *testing.T) {
 	t.Run("when there are no credential helpers, configures gh for repo and gist host", func(t *testing.T) {
 		hc := contract.NewHelperConfig(t)
diff --git a/pkg/cmd/auth/shared/git_credential.go b/pkg/cmd/auth/shared/git_credential.go
index e3136de43..90f250290 100644
--- a/pkg/cmd/auth/shared/git_credential.go
+++ b/pkg/cmd/auth/shared/git_credential.go
@@ -7,11 +7,13 @@ import (
 	"github.com/cli/cli/v2/pkg/cmd/auth/shared/gitcredentials"
 )
 
+// HelperConfig defines an interface for configuring and querying git credential helpers.
 type HelperConfig interface {
 	ConfigureOurs(hostname string) error
 	ConfiguredHelper(hostname string) (gitcredentials.Helper, error)
 }
 
+// GitCredentialFlow manages the interactive flow for configuring git credential helpers during authentication.
 type GitCredentialFlow struct {
 	Prompter Prompt
 
@@ -23,6 +25,7 @@ type GitCredentialFlow struct {
 	scopes      []string
 }
 
+// Prompt asks the user whether to configure git credentials for the given hostname.
 func (flow *GitCredentialFlow) Prompt(hostname string) error {
 	// First we'll fetch the credential helper that would be used for this host
 	var configuredHelperErr error
@@ -69,14 +72,17 @@ func (flow *GitCredentialFlow) Prompt(hostname string) error {
 	return nil
 }
 
+// Scopes returns the additional OAuth scopes required by the credential flow.
 func (flow *GitCredentialFlow) Scopes() []string {
 	return flow.scopes
 }
 
+// ShouldSetup reports whether the user opted to configure git credentials.
 func (flow *GitCredentialFlow) ShouldSetup() bool {
 	return flow.shouldSetup
 }
 
+// Setup configures git credential storage for the given hostname, username, and token.
 func (flow *GitCredentialFlow) Setup(hostname, username, authToken string) error {
 	// If there is no credential helper configured then we will set ourselves up as
 	// the credential helper for this host.
diff --git a/pkg/cmd/auth/shared/gitcredentials/fake_helper_config.go b/pkg/cmd/auth/shared/gitcredentials/fake_helper_config.go
index f6ae2f2c0..7ca1e01b6 100644
--- a/pkg/cmd/auth/shared/gitcredentials/fake_helper_config.go
+++ b/pkg/cmd/auth/shared/gitcredentials/fake_helper_config.go
@@ -7,6 +7,7 @@ import (
 	"github.com/cli/cli/v2/internal/ghinstance"
 )
 
+// FakeHelperConfig is a test double for HelperConfig that uses in-memory state.
 type FakeHelperConfig struct {
 	SelfExecutablePath string
 	Helpers            map[string]Helper
diff --git a/pkg/cmd/auth/shared/login_flow.go b/pkg/cmd/auth/shared/login_flow.go
index cd018430d..5cfc09d4d 100644
--- a/pkg/cmd/auth/shared/login_flow.go
+++ b/pkg/cmd/auth/shared/login_flow.go
@@ -26,6 +26,7 @@ type iconfig interface {
 	UsersForHost(string) []string
 }
 
+// LoginOptions holds the shared configuration and dependencies for the authentication login flow.
 type LoginOptions struct {
 	IO               *iostreams.IOStreams
 	Config           iconfig
@@ -46,6 +47,7 @@ type LoginOptions struct {
 	sshContext ssh.Context
 }
 
+// Login performs the authentication flow using either interactive OAuth or a provided token.
 func Login(opts *LoginOptions) error {
 	cfg := opts.Config
 	hostname := opts.Hostname
@@ -249,6 +251,7 @@ func sshKeyUpload(httpClient *http.Client, hostname, keyFile string, title strin
 	return add.SSHKeyUpload(httpClient, hostname, f, title)
 }
 
+// GetCurrentLogin queries the GitHub API to retrieve the username of the currently authenticated user.
 func GetCurrentLogin(httpClient httpClient, hostname, authToken string) (string, error) {
 	query := `query UserCurrent{viewer{login}}`
 	reqBody, err := json.Marshal(map[string]interface{}{"query": query})
diff --git a/pkg/cmd/auth/shared/oauth_scopes.go b/pkg/cmd/auth/shared/oauth_scopes.go
index 8d9996019..3748259c3 100644
--- a/pkg/cmd/auth/shared/oauth_scopes.go
+++ b/pkg/cmd/auth/shared/oauth_scopes.go
@@ -10,10 +10,12 @@ import (
 	"github.com/cli/cli/v2/internal/ghinstance"
 )
 
+// MissingScopesError indicates that the authentication token is missing required OAuth scopes.
 type MissingScopesError struct {
 	MissingScopes []string
 }
 
+// Error returns a human-readable message listing the missing OAuth scopes.
 func (e MissingScopesError) Error() string {
 	var missing []string
 	for _, s := range e.MissingScopes {
diff --git a/pkg/cmd/auth/shared/prompt.go b/pkg/cmd/auth/shared/prompt.go
index c0d47372c..a077fcb22 100644
--- a/pkg/cmd/auth/shared/prompt.go
+++ b/pkg/cmd/auth/shared/prompt.go
@@ -1,5 +1,6 @@
 package shared
 
+// Prompt defines an interface for interactive user prompts during authentication flows.
 type Prompt interface {
 	Select(string, string, []string) (int, error)
 	Confirm(string, bool) (bool, error)
diff --git a/pkg/cmd/auth/shared/writeable.go b/pkg/cmd/auth/shared/writeable.go
index 381c7e02a..985ae161e 100644
--- a/pkg/cmd/auth/shared/writeable.go
+++ b/pkg/cmd/auth/shared/writeable.go
@@ -6,6 +6,7 @@ import (
 	"github.com/cli/cli/v2/internal/gh"
 )
 
+// AuthTokenWriteable returns the token source and whether the token for the given hostname can be modified.
 func AuthTokenWriteable(authCfg gh.AuthConfig, hostname string) (string, bool) {
 	token, src := authCfg.ActiveToken(hostname)
 	return src, (token == "" || !strings.HasSuffix(src, "_TOKEN"))
diff --git a/pkg/cmd/auth/status/status.go b/pkg/cmd/auth/status/status.go
index 348b9531d..c7773383e 100644
--- a/pkg/cmd/auth/status/status.go
+++ b/pkg/cmd/auth/status/status.go
@@ -53,10 +53,12 @@ var authStatusFields = []string{
 	"hosts",
 }
 
+// ExportData returns the auth status fields as a map suitable for structured output.
 func (a authStatus) ExportData(fields []string) map[string]interface{} {
 	return cmdutil.StructExportData(a, fields)
 }
 
+// String returns a human-readable representation of the auth entry using the given color scheme.
 func (e authEntry) String(cs *iostreams.ColorScheme) string {
 	var sb strings.Builder
 
@@ -114,6 +116,7 @@ func (e authEntry) String(cs *iostreams.ColorScheme) string {
 	return sb.String()
 }
 
+// StatusOptions holds the configuration and dependencies for the status command.
 type StatusOptions struct {
 	HttpClient func() (*http.Client, error)
 	IO         *iostreams.IOStreams
@@ -125,6 +128,7 @@ type StatusOptions struct {
 	Active    bool
 }
 
+// NewCmdStatus creates the 'auth status' command for displaying authentication status.
 func NewCmdStatus(f *cmdutil.Factory, runF func(*StatusOptions) error) *cobra.Command {
 	opts := &StatusOptions{
 		HttpClient: f.HttpClient,
diff --git a/pkg/cmd/auth/switch/switch.go b/pkg/cmd/auth/switch/switch.go
index 8822c407b..617c280b9 100644
--- a/pkg/cmd/auth/switch/switch.go
+++ b/pkg/cmd/auth/switch/switch.go
@@ -13,6 +13,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// SwitchOptions holds the configuration and dependencies for the switch command.
 type SwitchOptions struct {
 	IO       *iostreams.IOStreams
 	Config   func() (gh.Config, error)
@@ -21,6 +22,7 @@ type SwitchOptions struct {
 	Username string
 }
 
+// NewCmdSwitch creates the 'auth switch' command for switching between authenticated accounts.
 func NewCmdSwitch(f *cmdutil.Factory, runF func(*SwitchOptions) error) *cobra.Command {
 	opts := SwitchOptions{
 		IO:       f.IOStreams,
diff --git a/pkg/cmd/auth/token/token.go b/pkg/cmd/auth/token/token.go
index d9faac7d8..3bde2daee 100644
--- a/pkg/cmd/auth/token/token.go
+++ b/pkg/cmd/auth/token/token.go
@@ -11,6 +11,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// TokenOptions holds the configuration and dependencies for the token command.
 type TokenOptions struct {
 	IO     *iostreams.IOStreams
 	Config func() (gh.Config, error)
@@ -20,6 +21,7 @@ type TokenOptions struct {
 	SecureStorage bool
 }
 
+// NewCmdToken creates the 'auth token' command for displaying or managing the authentication token.
 func NewCmdToken(f *cmdutil.Factory, runF func(*TokenOptions) error) *cobra.Command {
 	opts := &TokenOptions{
 		IO:     f.IOStreams,