From df295a1dba816e7340b8e9930442929f64516ee4 Mon Sep 17 00:00:00 2001
From: Kynan Ware <47394200+BagToad@users.noreply.github.com>
Date: Wed, 4 Mar 2026 16:14:05 -0700
Subject: [PATCH] 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 |  5 +++++
 pkg/cmd/config/config.go                  |  2 ++
 pkg/cmd/config/get/get.go                 |  7 +++++++
 pkg/cmd/config/list/list.go               |  5 +++++
 pkg/cmd/config/set/set.go                 | 12 ++++++++++++
 pkg/cmd/root/alias.go                     |  5 +++++
 pkg/cmd/root/extension.go                 |  5 +++++
 pkg/cmd/root/help.go                      |  7 +++++++
 pkg/cmd/root/help_topic.go                |  5 +++++
 pkg/cmd/root/root.go                      |  7 +++++++
 10 files changed, 60 insertions(+)

diff --git a/pkg/cmd/config/clear-cache/clear_cache.go b/pkg/cmd/config/clear-cache/clear_cache.go
index 71cd1a57a..41b060d60 100644
--- a/pkg/cmd/config/clear-cache/clear_cache.go
+++ b/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,
diff --git a/pkg/cmd/config/config.go b/pkg/cmd/config/config.go
index 5f8242d2a..8781ee980 100644
--- a/pkg/cmd/config/config.go
+++ b/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")
diff --git a/pkg/cmd/config/get/get.go b/pkg/cmd/config/get/get.go
index 17892485c..663bce5b2 100644
--- a/pkg/cmd/config/get/get.go
+++ b/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)
 }
diff --git a/pkg/cmd/config/list/list.go b/pkg/cmd/config/list/list.go
index 1cfb92c87..0ef09c054 100644
--- a/pkg/cmd/config/list/list.go
+++ b/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,
diff --git a/pkg/cmd/config/set/set.go b/pkg/cmd/config/set/set.go
index a1fb2bbe9..4cfbe258f 100644
--- a/pkg/cmd/config/set/set.go
+++ b/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
 
diff --git a/pkg/cmd/root/alias.go b/pkg/cmd/root/alias.go
index 4f504f2b8..2df9d70e5 100644
--- a/pkg/cmd/root/alias.go
+++ b/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,
diff --git a/pkg/cmd/root/extension.go b/pkg/cmd/root/extension.go
index 7e2d7aca7..f52ae75da 100644
--- a/pkg/cmd/root/extension.go
+++ b/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()
diff --git a/pkg/cmd/root/help.go b/pkg/cmd/root/help.go
index 2676cdd15..95da42fb9 100644
--- a/pkg/cmd/root/help.go
+++ b/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
diff --git a/pkg/cmd/root/help_topic.go b/pkg/cmd/root/help_topic.go
index a375d9e20..23aa2edf0 100644
--- a/pkg/cmd/root/help_topic.go
+++ b/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,
diff --git a/pkg/cmd/root/root.go b/pkg/cmd/root/root.go
index ed33f568e..756b48978 100644
--- a/pkg/cmd/root/root.go
+++ b/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()