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

@@ -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>",

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,

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,

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,

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,

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,

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)

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.

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

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

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 {

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)

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"))

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,

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,

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,