Add godoc comments to exported symbols in pkg/cmd/config and pkg/cmd/root

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

pkg/cmd/config/clear-cache/clear_cache.go

@@ -11,11 +11,16 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// ClearCacheOptions is documented here.
+// ClearCacheOptions holds the options for the config clear-cache command.
 type ClearCacheOptions struct {
 	IO       *iostreams.IOStreams
 	CacheDir string
 }
 
+// NewCmdConfigClearCache is documented here.
+
+// NewCmdConfigClearCache returns a cobra command for clearing the gh cache.
 func NewCmdConfigClearCache(f *cmdutil.Factory, runF func(*ClearCacheOptions) error) *cobra.Command {
 	opts := &ClearCacheOptions{
 		IO:       f.IOStreams,

pkg/cmd/config/config.go

@@ -13,6 +13,8 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// NewCmdConfig is documented here.
+// NewCmdConfig returns a cobra command for managing gh configuration settings.
 func NewCmdConfig(f *cmdutil.Factory) *cobra.Command {
 	longDoc := strings.Builder{}
 	longDoc.WriteString("Display or change configuration settings for gh.\n\n")

pkg/cmd/config/get/get.go

@@ -11,6 +11,8 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// GetOptions is documented here.
+// GetOptions holds the options for the config get command.
 type GetOptions struct {
 	IO     *iostreams.IOStreams
 	Config gh.Config
@@ -19,6 +21,9 @@ type GetOptions struct {
 	Key      string
 }
 
+// NewCmdConfigGet is documented here.
+
+// NewCmdConfigGet returns a cobra command for retrieving a configuration value.
 func NewCmdConfigGet(f *cmdutil.Factory, runF func(*GetOptions) error) *cobra.Command {
 	opts := &GetOptions{
 		IO: f.IOStreams,
@@ -77,8 +82,10 @@ func getRun(opts *GetOptions) error {
 
 type nonExistentKeyError struct {
 	key string
+// Error is documented here.
 }
 
+// Error returns a message indicating the configuration key was not found.
 func (e nonExistentKeyError) Error() string {
 	return fmt.Sprintf("could not find key \"%s\"", e.key)
 }

pkg/cmd/config/list/list.go

@@ -10,6 +10,8 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// ListOptions is documented here.
+// ListOptions holds the options for the config list command.
 type ListOptions struct {
 	IO     *iostreams.IOStreams
 	Config func() (gh.Config, error)
@@ -17,6 +19,9 @@ type ListOptions struct {
 	Hostname string
 }
 
+// NewCmdConfigList is documented here.
+
+// NewCmdConfigList returns a cobra command for listing configuration settings.
 func NewCmdConfigList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Command {
 	opts := &ListOptions{
 		IO:     f.IOStreams,

pkg/cmd/config/set/set.go

@@ -13,6 +13,8 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// SetOptions is documented here.
+// SetOptions holds the options for the config set command.
 type SetOptions struct {
 	IO     *iostreams.IOStreams
 	Config gh.Config
@@ -22,6 +24,9 @@ type SetOptions struct {
 	Hostname string
 }
 
+// NewCmdConfigSet is documented here.
+
+// NewCmdConfigSet returns a cobra command for updating a configuration value.
 func NewCmdConfigSet(f *cmdutil.Factory, runF func(*SetOptions) error) *cobra.Command {
 	opts := &SetOptions{
 		IO: f.IOStreams,
@@ -85,8 +90,10 @@ func setRun(opts *SetOptions) error {
 		return fmt.Errorf("failed to write config to disk: %w", err)
 	}
 	return nil
+// ValidateKey is documented here.
 }
 
+// ValidateKey checks whether the given key is a known configuration key.
 func ValidateKey(key string) error {
 	for _, configKey := range config.Options {
 		if key == configKey.Key {
@@ -94,17 +101,22 @@ func ValidateKey(key string) error {
 		}
 	}
 
+	// InvalidValueError is documented here.
 	return fmt.Errorf("invalid key")
 }
 
+// InvalidValueError indicates that a configuration value is not among the allowed values.
 type InvalidValueError struct {
 	ValidValues []string
 }
 
+// ValidateValue is documented here.
+// Error returns a description of the invalid value error.
 func (e InvalidValueError) Error() string {
 	return "invalid value"
 }
 
+// ValidateValue checks whether the value is valid for the given configuration key.
 func ValidateValue(key, value string) error {
 	var validValues []string
 

pkg/cmd/root/alias.go

@@ -16,6 +16,8 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// NewCmdShellAlias is documented here.
+// NewCmdShellAlias returns a cobra command that executes a shell alias.
 func NewCmdShellAlias(io *iostreams.IOStreams, aliasName, aliasValue string) *cobra.Command {
 	return &cobra.Command{
 		Use:   aliasName,
@@ -47,6 +49,9 @@ func NewCmdShellAlias(io *iostreams.IOStreams, aliasName, aliasValue string) *co
 	}
 }
 
+// NewCmdAlias is documented here.
+
+// NewCmdAlias returns a cobra command that executes a gh command alias.
 func NewCmdAlias(io *iostreams.IOStreams, aliasName, aliasValue string) *cobra.Command {
 	return &cobra.Command{
 		Use:   aliasName,

pkg/cmd/root/extension.go

@@ -14,10 +14,15 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// ExternalCommandExitError is documented here.
+// ExternalCommandExitError wraps an exec.ExitError from an external command.
 type ExternalCommandExitError struct {
 	*exec.ExitError
 }
 
+// NewCmdExtension is documented here.
+
+// NewCmdExtension returns a cobra command that runs a gh CLI extension.
 func NewCmdExtension(io *iostreams.IOStreams, em extensions.ExtensionManager, ext extensions.Extension, checkExtensionReleaseInfo func(extensions.ExtensionManager, extensions.Extension) (*update.ReleaseInfo, error)) *cobra.Command {
 	updateMessageChan := make(chan *update.ReleaseInfo)
 	cs := io.ColorScheme()

pkg/cmd/root/help.go

@@ -237,11 +237,16 @@ func findCommand(cmd *cobra.Command, name string) *cobra.Command {
 	return nil
 }
 
+// CommandGroup is documented here.
+// CommandGroup represents a titled group of related commands.
 type CommandGroup struct {
 	Title    string
 	Commands []*cobra.Command
 }
 
+// GroupedCommands is documented here.
+
+// GroupedCommands returns the subcommands of cmd organized into groups.
 func GroupedCommands(cmd *cobra.Command) []CommandGroup {
 	var res []CommandGroup
 
@@ -310,8 +315,10 @@ func dedent(s string) string {
 		fmt.Fprintln(&buf, strings.TrimPrefix(l, strings.Repeat(" ", minIndent)))
 	}
 	return strings.TrimSuffix(buf.String(), "\n")
+// BuildAliasList is documented here.
 }
 
+// BuildAliasList collects all alias names for the given command and its parents.
 func BuildAliasList(cmd *cobra.Command, aliases []string) []string {
 	if !cmd.HasParent() {
 		return aliases

pkg/cmd/root/help_topic.go

@@ -17,6 +17,8 @@ type helpTopic struct {
 	example string
 }
 
+// HelpTopics is documented here.
+// HelpTopics is the list of additional help topics available in gh.
 var HelpTopics = []helpTopic{
 	{
 		name:  "mintty",
@@ -306,6 +308,9 @@ var HelpTopics = []helpTopic{
 	},
 }
 
+// NewCmdHelpTopic is documented here.
+
+// NewCmdHelpTopic returns a cobra command that displays a help topic.
 func NewCmdHelpTopic(ios *iostreams.IOStreams, ht helpTopic) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     ht.name,

pkg/cmd/root/root.go

@@ -48,14 +48,21 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// AuthError is documented here.
+// AuthError represents an authentication failure.
 type AuthError struct {
 	err error
 }
 
+// Error is documented here.
+
+// Error returns the underlying authentication error message.
 func (ae *AuthError) Error() string {
 	return ae.err.Error()
+// NewCmdRoot is documented here.
 }
 
+// NewCmdRoot creates the root cobra command for the gh CLI.
 func NewCmdRoot(f *cmdutil.Factory, version, buildDate string) (*cobra.Command, error) {
 	io := f.IOStreams
 	cfg, err := f.Config()