Add godoc comments to exported symbols in remaining packages

Add documentation comments to exported symbols across all remaining
smaller packages including cmd/gen-docs, context, internal/browser,
internal/gh, internal/ghcmd, internal/ghinstance, internal/ghrepo,
internal/keyring, internal/run, internal/safepaths, internal/tableprinter,
internal/text, internal/update, pkg/cmd/accessibility, pkg/cmd/actions,
pkg/cmd/alias, pkg/cmd/api, pkg/cmd/browse, pkg/cmd/cache,
pkg/cmd/completion, pkg/cmd/copilot, pkg/cmd/factory, pkg/cmd/gpg-key,
pkg/cmd/label, pkg/cmd/licenses, pkg/cmd/org, pkg/cmd/preview,
pkg/cmd/ssh-key, pkg/cmd/version, pkg/extensions, pkg/jsoncolor,
pkg/markdown, pkg/option, pkg/set, pkg/ssh, pkg/surveyext, test,
internal/authflow, and utils.

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

cmd/gen-docs/main.go

@@ -91,6 +91,7 @@ func linkHandler(name string) string {
 // Implements browser.Browser interface.
 type browser struct{}
 
+// Browse opens the given URL in a browser.
 func (b *browser) Browse(_ string) error {
 	return nil
 }
@@ -98,36 +99,45 @@ func (b *browser) Browse(_ string) error {
 // Implements extensions.ExtensionManager interface.
 type em struct{}
 
+// List returns the list of installed extensions.
 func (e *em) List() []extensions.Extension {
 	return nil
 }
 
+// Install installs an extension from a repository.
 func (e *em) Install(_ ghrepo.Interface, _ string) error {
 	return nil
 }
 
+// InstallLocal installs an extension from a local directory.
 func (e *em) InstallLocal(_ string) error {
 	return nil
 }
 
+// Upgrade upgrades an installed extension.
 func (e *em) Upgrade(_ string, _ bool) error {
 	return nil
 }
 
+// Remove deletes a value from the set.
 func (e *em) Remove(_ string) error {
 	return nil
 }
 
+// Dispatch executes an installed extension.
 func (e *em) Dispatch(_ []string, _ io.Reader, _, _ io.Writer) (bool, error) {
 	return false, nil
 }
 
+// Create initializes a new extension project.
 func (e *em) Create(_ string, _ extensions.ExtTemplateType) error {
 	return nil
 }
 
+// EnableDryRunMode enables dry run mode for the extension manager.
 func (e *em) EnableDryRunMode() {}
 
+// UpdateDir sets the directory used for extension updates.
 func (e *em) UpdateDir(_ string) string {
 	return ""
 }

context/context.go

@@ -16,6 +16,7 @@ import (
 // unusually large number of git remotes.
 const defaultRemotesForLookup = 5
 
+// ResolveRemotesToRepos maps git remotes to GitHub repositories.
 func ResolveRemotesToRepos(remotes Remotes, client *api.Client, base string) (*ResolvedRemotes, error) {
 	sort.Stable(remotes)
 
@@ -51,6 +52,7 @@ func resolveNetwork(result *ResolvedRemotes, remotesForLookup int) error {
 	return err
 }
 
+// ResolvedRemotes holds git remotes that have been mapped to GitHub repositories.
 type ResolvedRemotes struct {
 	baseOverride ghrepo.Interface
 	remotes      Remotes
@@ -58,6 +60,7 @@ type ResolvedRemotes struct {
 	apiClient    *api.Client
 }
 
+// BaseRepo determines the base repository from resolved remotes.
 func (r *ResolvedRemotes) BaseRepo(io *iostreams.IOStreams) (ghrepo.Interface, error) {
 	if r.baseOverride != nil {
 		return r.baseOverride, nil
@@ -108,6 +111,7 @@ func (r *ResolvedRemotes) BaseRepo(io *iostreams.IOStreams) (ghrepo.Interface, e
 		"please run `gh repo set-default` to select a default remote repository.")
 }
 
+// HeadRepos returns candidate head repositories for pull requests.
 func (r *ResolvedRemotes) HeadRepos() ([]*api.Repository, error) {
 	if r.network == nil {
 		err := resolveNetwork(r, defaultRemotesForLookup)

context/remote.go

@@ -48,6 +48,7 @@ func (r Remotes) FilterByHosts(hosts []string) Remotes {
 	return filtered
 }
 
+// ResolvedRemote returns the resolved remote information.
 func (r Remotes) ResolvedRemote() (*Remote, error) {
 	for _, rr := range r {
 		if rr.Resolved != "" {
@@ -72,7 +73,9 @@ func remoteNameSortScore(name string) int {
 
 // https://golang.org/pkg/sort/#Interface
 func (r Remotes) Len() int      { return len(r) }
+// Swap exchanges elements i and j in Remotes.
 func (r Remotes) Swap(i, j int) { r[i], r[j] = r[j], r[i] }
+// Less reports whether element i should sort before element j.
 func (r Remotes) Less(i, j int) bool {
 	return remoteNameSortScore(r[i].Name) > remoteNameSortScore(r[j].Name)
 }
@@ -98,10 +101,12 @@ func (r Remote) RepoHost() string {
 	return r.Repo.RepoHost()
 }
 
+// Translator defines the interface for translating remote URLs.
 type Translator interface {
 	Translate(*url.URL) *url.URL
 }
 
+// TranslateRemotes converts git remotes using a URL translator.
 func TranslateRemotes(gitRemotes git.RemoteSet, translator Translator) (remotes Remotes) {
 	for _, r := range gitRemotes {
 		var repo ghrepo.Interface

internal/authflow/flow.go

@@ -119,6 +119,7 @@ type cfg struct {
 	token string
 }
 
+// ActiveToken performs the ActiveToken operation on cfg.
 func (c cfg) ActiveToken(hostname string) (string, string) {
 	return c.token, "oauth_token"
 }

internal/browser/browser.go

@@ -6,10 +6,12 @@ import (
 	ghBrowser "github.com/cli/go-gh/v2/pkg/browser"
 )
 
+// Browser defines the interface for opening URLs in a browser.
 type Browser interface {
 	Browse(string) error
 }
 
+// New creates and returns a new instance with default settings.
 func New(launcher string, stdout, stderr io.Writer) Browser {
 	b := ghBrowser.New(launcher, stdout, stderr)
 	return b

internal/browser/stub.go

@@ -1,14 +1,17 @@
 package browser
 
+// Stub is a mock browser for testing.
 type Stub struct {
 	urls []string
 }
 
+// Browse opens the given URL in a browser.
 func (b *Stub) Browse(url string) error {
 	b.urls = append(b.urls, url)
 	return nil
 }
 
+// BrowsedURL returns the URL that was browsed.
 func (b *Stub) BrowsedURL() string {
 	if len(b.urls) > 0 {
 		return b.urls[0]
@@ -21,6 +24,7 @@ type _testing interface {
 	Helper()
 }
 
+// Verify asserts that the expected URL was browsed.
 func (b *Stub) Verify(t _testing, url string) {
 	t.Helper()
 	if url != "" {

internal/gh/gh.go

@@ -14,13 +14,17 @@ import (
 	ghConfig "github.com/cli/go-gh/v2/pkg/config"
 )
 
+// ConfigSource indicates whether a config value was provided by the user or is a default.
 type ConfigSource string
 
 const (
+	// ConfigDefaultProvided indicates the value is a built-in default.
 	ConfigDefaultProvided ConfigSource = "default"
+	// ConfigUserProvided indicates the value was explicitly set by the user.
 	ConfigUserProvided    ConfigSource = "user"
 )
 
+// ConfigEntry represents a single configuration key-value pair.
 type ConfigEntry struct {
 	Value  string
 	Source ConfigSource

internal/gh/projects.go

@@ -18,6 +18,8 @@ type projectsV1Unsupported struct{}
 func (projectsV1Unsupported) sealed() {}
 
 var (
+	// ProjectsV1Supported indicates the host supports classic projects.
 	ProjectsV1Supported   ProjectsV1Support = projectsV1Supported{}
+	// ProjectsV1Unsupported indicates the host does not support classic projects.
 	ProjectsV1Unsupported ProjectsV1Support = projectsV1Unsupported{}
 )

internal/ghcmd/cmd.go

@@ -39,6 +39,7 @@ const (
 	exitPending exitCode = 8
 )
 
+// Main is the entry point for the gh command.
 func Main() exitCode {
 	buildDate := build.Date
 	buildVersion := build.Version

internal/ghinstance/host.go

@@ -33,6 +33,7 @@ func isGarage(h string) bool {
 	return strings.EqualFold(h, "garage.github.com")
 }
 
+// HostnameValidator returns a function that validates GitHub hostnames.
 func HostnameValidator(hostname string) error {
 	if len(strings.TrimSpace(hostname)) < 1 {
 		return errors.New("a value is required")
@@ -43,6 +44,7 @@ func HostnameValidator(hostname string) error {
 	return nil
 }
 
+// GraphQLEndpoint returns the GraphQL API endpoint for the given host.
 func GraphQLEndpoint(hostname string) string {
 	if isGarage(hostname) {
 		return fmt.Sprintf("https://%s/api/graphql", hostname)
@@ -56,6 +58,7 @@ func GraphQLEndpoint(hostname string) string {
 	return fmt.Sprintf("https://api.%s/graphql", hostname)
 }
 
+// RESTPrefix returns the REST API URL prefix for the given host.
 func RESTPrefix(hostname string) string {
 	if isGarage(hostname) {
 		return fmt.Sprintf("https://%s/api/v3/", hostname)
@@ -69,6 +72,7 @@ func RESTPrefix(hostname string) string {
 	return fmt.Sprintf("https://api.%s/", hostname)
 }
 
+// GistPrefix returns the Gist URL prefix for the given host.
 func GistPrefix(hostname string) string {
 	prefix := "https://"
 	if strings.EqualFold(hostname, localhost) {
@@ -77,6 +81,7 @@ func GistPrefix(hostname string) string {
 	return prefix + GistHost(hostname)
 }
 
+// GistHost returns the Gist host for the given GitHub host.
 func GistHost(hostname string) string {
 	if isGarage(hostname) {
 		return fmt.Sprintf("%s/gist/", hostname)
@@ -90,6 +95,7 @@ func GistHost(hostname string) string {
 	return fmt.Sprintf("gist.%s/", hostname)
 }
 
+// HostPrefix returns the URL prefix for the given host.
 func HostPrefix(hostname string) string {
 	if strings.EqualFold(hostname, localhost) {
 		return fmt.Sprintf("http://%s/", hostname)

internal/ghrepo/repo.go

@@ -82,6 +82,7 @@ func IsSame(a, b Interface) bool {
 		normalizeHostname(a.RepoHost()) == normalizeHostname(b.RepoHost())
 }
 
+// GenerateRepoURL constructs a URL for the given repository and path.
 func GenerateRepoURL(repo Interface, p string, args ...interface{}) string {
 	baseURL := fmt.Sprintf("%s%s/%s", ghinstance.HostPrefix(repo.RepoHost()), repo.RepoOwner(), repo.RepoName())
 	if p != "" {
@@ -92,6 +93,7 @@ func GenerateRepoURL(repo Interface, p string, args ...interface{}) string {
 	return baseURL
 }
 
+// FormatRemoteURL formats a remote URL for the given repository.
 func FormatRemoteURL(repo Interface, protocol string) string {
 	if protocol == "ssh" {
 		if tenant, found := ghinstance.TenantName(repo.RepoHost()); found {
@@ -108,14 +110,17 @@ type ghRepo struct {
 	hostname string
 }
 
+// RepoOwner returns the owner of the repository.
 func (r ghRepo) RepoOwner() string {
 	return r.owner
 }
 
+// RepoName returns the name of the repository.
 func (r ghRepo) RepoName() string {
 	return r.name
 }
 
+// RepoHost returns the host of the repository.
 func (r ghRepo) RepoHost() string {
 	return r.hostname
 }

internal/keyring/keyring.go

@@ -8,12 +8,15 @@ import (
 	"github.com/zalando/go-keyring"
 )
 
+// ErrNotFound is returned when a keyring entry is not found.
 var ErrNotFound = errors.New("secret not found in keyring")
 
+// TimeoutError represents an error returned by the operation.
 type TimeoutError struct {
 	message string
 }
 
+// Error returns the error message for TimeoutError.
 func (e *TimeoutError) Error() string {
 	return e.message
 }
@@ -73,10 +76,12 @@ func Delete(service, user string) error {
 	}
 }
 
+// MockInit sets up a mock keyring for testing.
 func MockInit() {
 	keyring.MockInit()
 }
 
+// MockInitWithError sets up a mock keyring that returns the given error.
 func MockInitWithError(err error) {
 	keyring.MockInitWithError(err)
 }

internal/run/run.go

@@ -30,6 +30,7 @@ type cmdWithStderr struct {
 	*exec.Cmd
 }
 
+// Output runs the cmdWithStderr and returns its output.
 func (c cmdWithStderr) Output() ([]byte, error) {
 	if isVerbose, _ := utils.IsDebugEnabled(); isVerbose {
 		_ = printArgs(os.Stderr, c.Cmd.Args)
@@ -49,6 +50,7 @@ func (c cmdWithStderr) Output() ([]byte, error) {
 	return out, cmdErr
 }
 
+// Run executes the cmdWithStderr command.
 func (c cmdWithStderr) Run() error {
 	if isVerbose, _ := utils.IsDebugEnabled(); isVerbose {
 		_ = printArgs(os.Stderr, c.Cmd.Args)
@@ -76,6 +78,7 @@ type CmdError struct {
 	Stderr *bytes.Buffer
 }
 
+// Error returns the error message for CmdError.
 func (e CmdError) Error() string {
 	msg := e.Stderr.String()
 	if msg != "" && !strings.HasSuffix(msg, "\n") {
@@ -84,6 +87,7 @@ func (e CmdError) Error() string {
 	return fmt.Sprintf("%s%s: %s", msg, e.Args[0], e.Err)
 }
 
+// Unwrap returns the underlying error for CmdError.
 func (e CmdError) Unwrap() error {
 	return e.Err
 }

internal/run/stub.go

@@ -12,6 +12,7 @@ const (
 	gitAuthRE = `-c credential(?:\..+)?\.helper= -c credential(?:\..+)?\.helper=!"[^"]+" auth git-credential `
 )
 
+// T defines the interface for t.
 type T interface {
 	Helper()
 	Errorf(string, ...interface{})
@@ -96,6 +97,7 @@ func (cs *CommandStubber) find(args []string) *commandStub {
 	return nil
 }
 
+// CommandCallback is a function that handles command execution in stubs.
 type CommandCallback func([]string)
 
 type commandStub struct {
@@ -111,10 +113,12 @@ type errWithExitCode struct {
 	exitCode int
 }
 
+// Error returns the error message for errWithExitCode.
 func (e errWithExitCode) Error() string {
 	return e.message
 }
 
+// ExitCode returns the exit code of the command.
 func (e errWithExitCode) ExitCode() int {
 	return e.exitCode
 }

internal/safepaths/absolute.go

@@ -64,11 +64,13 @@ func (a Absolute) isSubpathOf(dir Absolute) (bool, error) {
 	return !strings.HasPrefix(relativePath, ".."), nil
 }
 
+// PathTraversalError represents an error returned by the operation.
 type PathTraversalError struct {
 	Base  Absolute
 	Elems []string
 }
 
+// Error returns the error message for PathTraversalError.
 func (e PathTraversalError) Error() string {
 	return fmt.Sprintf("joining %s and %s would be a traversal", e.Base, filepath.Join(e.Elems...))
 }

internal/tableprinter/table_printer.go

@@ -10,6 +10,7 @@ import (
 	"github.com/cli/go-gh/v2/pkg/tableprinter"
 )
 
+// TablePrinter wraps the table printer with additional formatting options.
 type TablePrinter struct {
 	tableprinter.TablePrinter
 	isTTY bool
@@ -34,8 +35,11 @@ func (tp *TablePrinter) AddTimeField(now, t time.Time, c func(string) string) {
 }
 
 var (
+	// WithColor applies a color function to subsequent fields.
 	WithColor    = tableprinter.WithColor
+	// WithPadding applies padding to subsequent fields.
 	WithPadding  = tableprinter.WithPadding
+	// WithTruncate applies truncation to subsequent fields.
 	WithTruncate = tableprinter.WithTruncate
 )
 

internal/text/text.go

@@ -16,6 +16,7 @@ import (
 
 var whitespaceRE = regexp.MustCompile(`\s+`)
 
+// Indent prepends each line of the string with the given prefix.
 func Indent(s, indent string) string {
 	return text.Indent(s, indent)
 }
@@ -31,18 +32,22 @@ func RemoveExcessiveWhitespace(s string) string {
 	return whitespaceRE.ReplaceAllString(strings.TrimSpace(s), " ")
 }
 
+// DisplayWidth returns the display width of a string accounting for wide characters.
 func DisplayWidth(s string) int {
 	return text.DisplayWidth(s)
 }
 
+// Truncate shortens a string to fit within the given display width.
 func Truncate(maxWidth int, s string) string {
 	return text.Truncate(maxWidth, s)
 }
 
+// Pluralize returns the singular or plural form based on the count.
 func Pluralize(num int, thing string) string {
 	return text.Pluralize(num, thing)
 }
 
+// FuzzyAgo returns a human-friendly relative time string.
 func FuzzyAgo(a, b time.Time) string {
 	return text.RelativeTimeAgo(a, b)
 }
@@ -85,6 +90,7 @@ func RemoveDiacritics(value string) string {
 	return text.RemoveDiacritics(value)
 }
 
+// PadRight pads a string on the right to reach the specified width.
 func PadRight(maxWidth int, s string) string {
 	return text.PadRight(maxWidth, s)
 }

internal/update/update.go

@@ -28,6 +28,7 @@ type ReleaseInfo struct {
 	PublishedAt time.Time `json:"published_at"`
 }
 
+// StateEntry stores information about a CLI update check.
 type StateEntry struct {
 	CheckedForUpdateAt time.Time   `yaml:"checked_for_update_at"`
 	LatestRelease      ReleaseInfo `yaml:"latest_release"`

pkg/cmd/accessibility/accessibility.go

@@ -15,12 +15,14 @@ const (
 	webURL = "https://accessibility.github.com/conformance/cli/"
 )
 
+// AccessibilityOptions holds the options for the command.
 type AccessibilityOptions struct {
 	IO      *iostreams.IOStreams
 	Browser browser.Browser
 	Web     bool
 }
 
+// NewCmdAccessibility creates a new cobra command for the accessibility subcommand.
 func NewCmdAccessibility(f *cmdutil.Factory) *cobra.Command {
 	opts := AccessibilityOptions{
 		IO:      f.IOStreams,

pkg/cmd/actions/actions.go

@@ -7,6 +7,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// NewCmdActions creates a new cobra command for the actions subcommand.
 func NewCmdActions(f *cmdutil.Factory) *cobra.Command {
 	cs := f.IOStreams.ColorScheme()
 

pkg/cmd/alias/alias.go

@@ -10,6 +10,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// NewCmdAlias creates a new cobra command for the alias subcommand.
 func NewCmdAlias(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "alias <command>",

pkg/cmd/alias/delete/delete.go

@@ -10,6 +10,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// DeleteOptions holds the options for the command.
 type DeleteOptions struct {
 	Config func() (gh.Config, error)
 	IO     *iostreams.IOStreams
@@ -18,6 +19,7 @@ type DeleteOptions struct {
 	All  bool
 }
 
+// NewCmdDelete creates a new cobra command for the delete subcommand.
 func NewCmdDelete(f *cmdutil.Factory, runF func(*DeleteOptions) error) *cobra.Command {
 	opts := &DeleteOptions{
 		IO:     f.IOStreams,

pkg/cmd/alias/imports/import.go

@@ -14,6 +14,7 @@ import (
 	"gopkg.in/yaml.v3"
 )
 
+// ImportOptions holds the options for the command.
 type ImportOptions struct {
 	Config func() (gh.Config, error)
 	IO     *iostreams.IOStreams
@@ -25,6 +26,7 @@ type ImportOptions struct {
 	validAliasExpansion func(string) bool
 }
 
+// NewCmdImport creates a new cobra command for the import subcommand.
 func NewCmdImport(f *cmdutil.Factory, runF func(*ImportOptions) error) *cobra.Command {
 	opts := &ImportOptions{
 		IO:     f.IOStreams,

pkg/cmd/alias/list/list.go

@@ -9,11 +9,13 @@ import (
 	"gopkg.in/yaml.v3"
 )
 
+// ListOptions holds the options for the command.
 type ListOptions struct {
 	Config func() (gh.Config, error)
 	IO     *iostreams.IOStreams
 }
 
+// NewCmdList creates a new cobra command for the list subcommand.
 func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Command {
 	opts := &ListOptions{
 		IO:     f.IOStreams,

pkg/cmd/alias/set/set.go

@@ -13,6 +13,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// SetOptions holds the options for the command.
 type SetOptions struct {
 	Config func() (gh.Config, error)
 	IO     *iostreams.IOStreams
@@ -26,6 +27,7 @@ type SetOptions struct {
 	validAliasExpansion func(string) bool
 }
 
+// NewCmdSet creates a new cobra command for the set subcommand.
 func NewCmdSet(f *cmdutil.Factory, runF func(*SetOptions) error) *cobra.Command {
 	opts := &SetOptions{
 		IO:     f.IOStreams,

pkg/cmd/api/api.go

@@ -33,6 +33,7 @@ const (
 	ttyIndent = "  "
 )
 
+// ApiOptions holds the options for the command.
 type ApiOptions struct {
 	AppVersion string
 	BaseRepo   func() (ghrepo.Interface, error)
@@ -60,6 +61,7 @@ type ApiOptions struct {
 	Verbose             bool
 }
 
+// NewCmdApi creates a new cobra command for the api subcommand.
 func NewCmdApi(f *cmdutil.Factory, runF func(*ApiOptions) error) *cobra.Command {
 	opts := ApiOptions{
 		AppVersion: f.AppVersion,

pkg/cmd/api/pagination.go

@@ -120,6 +120,7 @@ type paginatedArrayReader struct {
 	cachedByte       byte
 }
 
+// Read reads data from the paginatedArrayReader.
 func (r *paginatedArrayReader) Read(p []byte) (int, error) {
 	var n int
 	var err error
@@ -157,6 +158,7 @@ type jsonArrayWriter struct {
 	color   bool
 }
 
+// Preface writes preliminary data before the main content.
 func (w *jsonArrayWriter) Preface() []json.Delim {
 	if w.started {
 		return []json.Delim{'['}
@@ -190,6 +192,7 @@ func (w *jsonArrayWriter) ReadFrom(r io.Reader) (int64, error) {
 	return written, nil
 }
 
+// Close closes the jsonArrayWriter and releases resources.
 func (w *jsonArrayWriter) Close() error {
 	var delims string
 	if w.started {

pkg/cmd/browse/browse.go

@@ -27,6 +27,7 @@ const (
 	emptyCommitFlag = "last"
 )
 
+// BrowseOptions holds the options for the command.
 type BrowseOptions struct {
 	BaseRepo         func() (ghrepo.Interface, error)
 	Browser          browser.Browser
@@ -49,6 +50,7 @@ type BrowseOptions struct {
 	HasRepoOverride bool
 }
 
+// NewCmdBrowse creates a new cobra command for the browse subcommand.
 func NewCmdBrowse(f *cmdutil.Factory, runF func(*BrowseOptions) error) *cobra.Command {
 	opts := &BrowseOptions{
 		Browser:    f.Browser,
@@ -368,10 +370,12 @@ type remoteGitClient struct {
 	httpClient func() (*http.Client, error)
 }
 
+// LastCommit returns the SHA of the last commit on the default branch.
 func (gc *localGitClient) LastCommit() (*git.Commit, error) {
 	return gc.client.LastCommit(context.Background())
 }
 
+// LastCommit returns the SHA of the last commit on the default branch.
 func (gc *remoteGitClient) LastCommit() (*git.Commit, error) {
 	httpClient, err := gc.httpClient()
 	if err != nil {

pkg/cmd/cache/cache.go

@@ -8,6 +8,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// NewCmdCache creates a new cobra command for the cache subcommand.
 func NewCmdCache(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "cache <command>",

pkg/cmd/cache/delete/delete.go

@@ -17,6 +17,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// DeleteOptions holds the options for the command.
 type DeleteOptions struct {
 	BaseRepo   func() (ghrepo.Interface, error)
 	HttpClient func() (*http.Client, error)
@@ -28,6 +29,7 @@ type DeleteOptions struct {
 	Ref               string
 }
 
+// NewCmdDelete creates a new cobra command for the delete subcommand.
 func NewCmdDelete(f *cmdutil.Factory, runF func(*DeleteOptions) error) *cobra.Command {
 	opts := &DeleteOptions{
 		IO:         f.IOStreams,

pkg/cmd/cache/list/list.go

@@ -17,6 +17,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// ListOptions holds the options for the command.
 type ListOptions struct {
 	BaseRepo   func() (ghrepo.Interface, error)
 	HttpClient func() (*http.Client, error)
@@ -31,6 +32,7 @@ type ListOptions struct {
 	Ref   string
 }
 
+// NewCmdList creates a new cobra command for the list subcommand.
 func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Command {
 	opts := ListOptions{
 		IO:         f.IOStreams,

pkg/cmd/cache/shared/shared.go

@@ -10,6 +10,7 @@ import (
 	"github.com/cli/cli/v2/pkg/cmdutil"
 )
 
+// CacheFields defines the list of exportable cache field names.
 var CacheFields = []string{
 	"createdAt",
 	"id",
@@ -20,6 +21,7 @@ var CacheFields = []string{
 	"version",
 }
 
+// Cache represents a GitHub Actions cache entry.
 type Cache struct {
 	CreatedAt      time.Time `json:"created_at"`
 	Id             int       `json:"id"`
@@ -30,11 +32,13 @@ type Cache struct {
 	Version        string    `json:"version"`
 }
 
+// CachePayload holds the paginated response of cache entries.
 type CachePayload struct {
 	ActionsCaches []Cache `json:"actions_caches"`
 	TotalCount    int     `json:"total_count"`
 }
 
+// GetCachesOptions holds the options for the command.
 type GetCachesOptions struct {
 	Limit int
 	Order string
@@ -92,6 +96,7 @@ pagination:
 	return result, nil
 }
 
+// ExportData returns the requested fields as exportable data.
 func (c *Cache) ExportData(fields []string) map[string]interface{} {
 	return cmdutil.StructExportData(c, fields)
 }

pkg/cmd/completion/completion.go

@@ -9,6 +9,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// NewCmdCompletion creates a new cobra command for the completion subcommand.
 func NewCmdCompletion(io *iostreams.IOStreams) *cobra.Command {
 	var shellType string
 

pkg/cmd/copilot/copilot.go

@@ -28,6 +28,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// CopilotOptions holds the options for the command.
 type CopilotOptions struct {
 	IO         *iostreams.IOStreams
 	HttpClient func() (*http.Client, error)
@@ -37,6 +38,7 @@ type CopilotOptions struct {
 	Remove      bool
 }
 
+// NewCmdCopilot creates a new cobra command for the copilot subcommand.
 func NewCmdCopilot(f *cmdutil.Factory, runF func(*CopilotOptions) error) *cobra.Command {
 	opts := &CopilotOptions{
 		IO:         f.IOStreams,

pkg/cmd/factory/default.go

@@ -26,6 +26,7 @@ import (
 var ssoHeader string
 var ssoURLRE = regexp.MustCompile(`\burl=([^;]+)`)
 
+// New creates and returns a new instance with default settings.
 func New(appVersion string) *cmdutil.Factory {
 	f := &cmdutil.Factory{
 		AppVersion:     appVersion,

pkg/cmd/factory/remote_resolver.go

@@ -14,6 +14,7 @@ import (
 )
 
 const (
+	// GH_HOST is g h_ h o s t.
 	GH_HOST = "GH_HOST"
 )
 
@@ -25,6 +26,7 @@ type remoteResolver struct {
 	remotesError  error
 }
 
+// Resolver returns a function that resolves remotes for the given factory.
 func (rr *remoteResolver) Resolver() func() (context.Remotes, error) {
 	return func() (context.Remotes, error) {
 		if rr.cachedRemotes != nil || rr.remotesError != nil {

pkg/cmd/gpg-key/add/add.go

@@ -14,6 +14,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// AddOptions holds the options for the command.
 type AddOptions struct {
 	IO         *iostreams.IOStreams
 	Config     func() (gh.Config, error)
@@ -23,6 +24,7 @@ type AddOptions struct {
 	Title   string
 }
 
+// NewCmdAdd creates a new cobra command for the add subcommand.
 func NewCmdAdd(f *cmdutil.Factory, runF func(*AddOptions) error) *cobra.Command {
 	opts := &AddOptions{
 		HTTPClient: f.HttpClient,

pkg/cmd/gpg-key/delete/delete.go

@@ -12,6 +12,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// DeleteOptions holds the options for the command.
 type DeleteOptions struct {
 	IO         *iostreams.IOStreams
 	Config     func() (gh.Config, error)
@@ -22,6 +23,7 @@ type DeleteOptions struct {
 	Prompter  prompter.Prompter
 }
 
+// NewCmdDelete creates a new cobra command for the delete subcommand.
 func NewCmdDelete(f *cmdutil.Factory, runF func(*DeleteOptions) error) *cobra.Command {
 	opts := &DeleteOptions{
 		HttpClient: f.HttpClient,

pkg/cmd/gpg-key/gpg_key.go

@@ -8,6 +8,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// NewCmdGPGKey creates a new cobra command for the g p g key subcommand.
 func NewCmdGPGKey(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "gpg-key <command>",

pkg/cmd/gpg-key/list/http.go

@@ -21,6 +21,7 @@ type email struct {
 	Email string `json:"email"`
 }
 
+// String returns the string representation of emails.
 func (es emails) String() string {
 	s := []string{}
 	for _, e := range es {

pkg/cmd/gpg-key/list/list.go

@@ -13,12 +13,14 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// ListOptions holds the options for the command.
 type ListOptions struct {
 	IO         *iostreams.IOStreams
 	Config     func() (gh.Config, error)
 	HTTPClient func() (*http.Client, error)
 }
 
+// NewCmdList creates a new cobra command for the list subcommand.
 func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Command {
 	opts := &ListOptions{
 		IO:         f.IOStreams,

pkg/cmd/label/http.go

@@ -44,6 +44,7 @@ type listQueryOptions struct {
 	fields []string
 }
 
+// OrderBy returns the GraphQL ordering clause.
 func (opts listQueryOptions) OrderBy() map[string]string {
 	// Set on copy to keep original intact.
 	if opts.Order == "" {

pkg/cmd/label/label.go

@@ -5,6 +5,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// NewCmdLabel creates a new cobra command for the label subcommand.
 func NewCmdLabel(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "label <command>",

pkg/cmd/label/shared.go

@@ -28,6 +28,7 @@ type label struct {
 	UpdatedAt   time.Time `json:"updatedAt"`
 }
 
+// ExportData returns the requested fields as exportable data.
 func (l *label) ExportData(fields []string) map[string]interface{} {
 	return cmdutil.StructExportData(l, fields)
 }

pkg/cmd/licenses/licenses.go

@@ -8,6 +8,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// NewCmdLicenses creates a new cobra command for the licenses subcommand.
 func NewCmdLicenses(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "licenses",

pkg/cmd/org/list/http.go

@@ -6,12 +6,14 @@ import (
 	"github.com/cli/cli/v2/api"
 )
 
+// OrganizationList holds a paginated list of organizations.
 type OrganizationList struct {
 	Organizations []Organization
 	TotalCount    int
 	User          string
 }
 
+// Organization represents a GitHub organization.
 type Organization struct {
 	Login string
 }

pkg/cmd/org/list/list.go

@@ -12,6 +12,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// ListOptions holds the options for the command.
 type ListOptions struct {
 	IO         *iostreams.IOStreams
 	Config     func() (gh.Config, error)
@@ -20,6 +21,7 @@ type ListOptions struct {
 	Limit int
 }
 
+// NewCmdList creates a new cobra command for the list subcommand.
 func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Command {
 	opts := ListOptions{
 		IO:         f.IOStreams,

pkg/cmd/org/org.go

@@ -7,6 +7,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// NewCmdOrg creates a new cobra command for the org subcommand.
 func NewCmdOrg(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "org <command>",

pkg/cmd/preview/preview.go

@@ -7,6 +7,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// NewCmdPreview creates a new cobra command for the preview subcommand.
 func NewCmdPreview(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "preview <command>",

pkg/cmd/preview/prompter/prompter.go

@@ -19,6 +19,7 @@ type prompterOptions struct {
 	PromptsToRun []func(prompter.Prompter, *iostreams.IOStreams) error
 }
 
+// NewCmdPrompter creates a new cobra command for the prompter subcommand.
 func NewCmdPrompter(f *cmdutil.Factory, runF func(*prompterOptions) error) *cobra.Command {
 	opts := &prompterOptions{
 		IO:     f.IOStreams,

pkg/cmd/ssh-key/add/add.go

@@ -13,6 +13,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// AddOptions holds the options for the command.
 type AddOptions struct {
 	IO         *iostreams.IOStreams
 	Config     func() (gh.Config, error)
@@ -23,6 +24,7 @@ type AddOptions struct {
 	Type    string
 }
 
+// NewCmdAdd creates a new cobra command for the add subcommand.
 func NewCmdAdd(f *cmdutil.Factory, runF func(*AddOptions) error) *cobra.Command {
 	opts := &AddOptions{
 		HTTPClient: f.HttpClient,

pkg/cmd/ssh-key/delete/delete.go

@@ -11,6 +11,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// DeleteOptions holds the options for the command.
 type DeleteOptions struct {
 	IO         *iostreams.IOStreams
 	Config     func() (gh.Config, error)
@@ -21,6 +22,7 @@ type DeleteOptions struct {
 	Prompter  prompter.Prompter
 }
 
+// NewCmdDelete creates a new cobra command for the delete subcommand.
 func NewCmdDelete(f *cmdutil.Factory, runF func(*DeleteOptions) error) *cobra.Command {
 	opts := &DeleteOptions{
 		HttpClient: f.HttpClient,

pkg/cmd/ssh-key/list/list.go

@@ -17,12 +17,14 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// ListOptions holds the options for the command.
 type ListOptions struct {
 	IO         *iostreams.IOStreams
 	Config     func() (gh.Config, error)
 	HTTPClient func() (*http.Client, error)
 }
 
+// NewCmdList creates a new cobra command for the list subcommand.
 func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Command {
 	opts := &ListOptions{
 		IO:         f.IOStreams,

pkg/cmd/ssh-key/shared/user_keys.go

@@ -12,7 +12,9 @@ import (
 )
 
 const (
+	// AuthenticationKey represents an SSH authentication key type.
 	AuthenticationKey = "authentication"
+	// SigningKey represents an SSH signing key type.
 	SigningKey        = "signing"
 )
 
@@ -24,6 +26,7 @@ type sshKey struct {
 	CreatedAt time.Time `json:"created_at"`
 }
 
+// UserKeys fetches the user's SSH authentication keys.
 func UserKeys(httpClient *http.Client, host, userHandle string) ([]sshKey, error) {
 	resource := "user/keys"
 	if userHandle != "" {
@@ -44,6 +47,7 @@ func UserKeys(httpClient *http.Client, host, userHandle string) ([]sshKey, error
 	return keys, nil
 }
 
+// UserSigningKeys fetches the user's SSH signing keys.
 func UserSigningKeys(httpClient *http.Client, host, userHandle string) ([]sshKey, error) {
 	resource := "user/ssh_signing_keys"
 	if userHandle != "" {

pkg/cmd/ssh-key/ssh_key.go

@@ -8,6 +8,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// NewCmdSSHKey creates a new cobra command for the s s h key subcommand.
 func NewCmdSSHKey(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "ssh-key <command>",

pkg/cmd/version/version.go

@@ -9,6 +9,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// NewCmdVersion creates a new cobra command for the version subcommand.
 func NewCmdVersion(f *cmdutil.Factory, version, buildDate string) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:    "version",
@@ -23,6 +24,7 @@ func NewCmdVersion(f *cmdutil.Factory, version, buildDate string) *cobra.Command
 	return cmd
 }
 
+// Format returns a formatted version string.
 func Format(version, buildDate string) string {
 	version = strings.TrimPrefix(version, "v")
 

pkg/extensions/extension.go

@@ -6,15 +6,21 @@ import (
 	"github.com/cli/cli/v2/internal/ghrepo"
 )
 
+// ExtTemplateType represents the type of extension template.
 type ExtTemplateType int
 
 const (
+	// GitTemplateType represents a git-based extension template.
 	GitTemplateType      ExtTemplateType = 0
+	// GoBinTemplateType represents a Go binary extension template.
 	GoBinTemplateType    ExtTemplateType = 1
+	// OtherBinTemplateType represents a precompiled binary extension template.
 	OtherBinTemplateType ExtTemplateType = 2
 )
 
 //go:generate moq -rm -out extension_mock.go . Extension
+
+// Extension defines the interface for a GitHub CLI extension.
 type Extension interface {
 	Name() string // Extension Name without gh-
 	Path() string // Path to executable
@@ -29,6 +35,8 @@ type Extension interface {
 }
 
 //go:generate moq -rm -out manager_mock.go . ExtensionManager
+
+// ExtensionManager defines the interface for managing CLI extensions.
 type ExtensionManager interface {
 	List() []Extension
 	Install(ghrepo.Interface, string) error

pkg/jsoncolor/jsoncolor.go

@@ -16,6 +16,7 @@ const (
 	colorBool   = "33"   // yellow
 )
 
+// JsonWriter defines the interface for json writer.
 type JsonWriter interface {
 	Preface() []json.Delim
 }

pkg/markdown/markdown.go

@@ -8,6 +8,7 @@ import (
 	ghMarkdown "github.com/cli/go-gh/v2/pkg/markdown"
 )
 
+// WithoutIndentation returns a render option that disables indentation.
 func WithoutIndentation() glamour.TermRendererOption {
 	return ghMarkdown.WithoutIndentation()
 }
@@ -27,14 +28,17 @@ func WithWrap(w int) glamour.TermRendererOption {
 	return ghMarkdown.WithWrap(w)
 }
 
+// WithTheme returns a render option that sets the glamour theme.
 func WithTheme(theme string) glamour.TermRendererOption {
 	return ghMarkdown.WithTheme(theme)
 }
 
+// WithBaseURL returns a render option that sets the base URL for relative links.
 func WithBaseURL(u string) glamour.TermRendererOption {
 	return ghMarkdown.WithBaseURL(u)
 }
 
+// Render converts markdown text to a terminal-friendly format.
 func Render(text string, opts ...glamour.TermRendererOption) (string, error) {
 	return ghMarkdown.Render(text, opts...)
 }

pkg/option/option.go

@@ -46,6 +46,7 @@ func None[T any]() Option[T] {
 	return Option[T]{}
 }
 
+// SomeIfNonZero is documented here.
 func SomeIfNonZero[T comparable](value T) Option[T] {
 	// value is a zero value then return a None
 	var zero T

pkg/set/string_set.go

@@ -7,6 +7,7 @@ type stringSet struct {
 	m map[string]struct{}
 }
 
+// NewStringSet creates a new set of strings.
 func NewStringSet() *stringSet {
 	s := &stringSet{}
 	s.m = make(map[string]struct{})
@@ -14,6 +15,7 @@ func NewStringSet() *stringSet {
 	return s
 }
 
+// Add inserts a value into the set.
 func (s *stringSet) Add(value string) {
 	if s.Contains(value) {
 		return
@@ -22,12 +24,14 @@ func (s *stringSet) Add(value string) {
 	s.v = append(s.v, value)
 }
 
+// AddValues inserts multiple values into the set.
 func (s *stringSet) AddValues(values []string) {
 	for _, v := range values {
 		s.Add(v)
 	}
 }
 
+// Remove deletes a value from the set.
 func (s *stringSet) Remove(value string) {
 	if !s.Contains(value) {
 		return
@@ -50,25 +54,30 @@ func sliceWithout(s []string, v string) []string {
 	return append(s[:idx], s[idx+1:]...)
 }
 
+// RemoveValues deletes multiple values from the set.
 func (s *stringSet) RemoveValues(values []string) {
 	for _, v := range values {
 		s.Remove(v)
 	}
 }
 
+// Contains reports whether the set contains the given value.
 func (s *stringSet) Contains(value string) bool {
 	_, c := s.m[value]
 	return c
 }
 
+// Len returns the number of elements in stringSet.
 func (s *stringSet) Len() int {
 	return len(s.m)
 }
 
+// ToSlice performs the ToSlice operation on stringSet.
 func (s *stringSet) ToSlice() []string {
 	return s.v
 }
 
+// Equal reports whether two sets contain the same elements.
 func (s1 *stringSet) Equal(s2 *stringSet) bool {
 	if s1.Len() != s2.Len() {
 		return false

pkg/ssh/ssh_keys.go

@@ -13,6 +13,7 @@ import (
 	"github.com/cli/safeexec"
 )
 
+// Context holds configuration for SSH key operations.
 type Context struct {
 	configDir string
 	keygenExe string
@@ -27,13 +28,16 @@ func NewContextForTests(configDir, keygenExe string) Context {
 	}
 }
 
+// KeyPair holds a public and private SSH key pair.
 type KeyPair struct {
 	PublicKeyPath  string
 	PrivateKeyPath string
 }
 
+// ErrKeyAlreadyExists is returned when an SSH key already exists.
 var ErrKeyAlreadyExists = errors.New("SSH key already exists")
 
+// LocalPublicKeys returns the list of public SSH keys found locally.
 func (c *Context) LocalPublicKeys() ([]string, error) {
 	sshDir, err := c.SshDir()
 	if err != nil {
@@ -43,11 +47,13 @@ func (c *Context) LocalPublicKeys() ([]string, error) {
 	return filepath.Glob(filepath.Join(sshDir, "*.pub"))
 }
 
+// HasKeygen reports whether ssh-keygen is available.
 func (c *Context) HasKeygen() bool {
 	_, err := c.findKeygen()
 	return err == nil
 }
 
+// GenerateSSHKey generates a new SSH key pair.
 func (c *Context) GenerateSSHKey(keyName string, passphrase string) (*KeyPair, error) {
 	keygenExe, err := c.findKeygen()
 	if err != nil {
@@ -88,6 +94,7 @@ func (c *Context) GenerateSSHKey(keyName string, passphrase string) (*KeyPair, e
 	return &keyPair, nil
 }
 
+// SshDir returns the path to the SSH directory.
 func (c *Context) SshDir() (string, error) {
 	if c.configDir != "" {
 		return c.configDir, nil

pkg/surveyext/editor.go

@@ -159,6 +159,7 @@ func (e *GhEditor) Prompt(config *survey.PromptConfig) (interface{}, error) {
 	return e.prompt(initialValue, config)
 }
 
+// EditorName returns the name of the user's preferred text editor.
 func EditorName(editorCommand string) string {
 	if editorCommand == "" {
 		editorCommand = defaultEditor

pkg/surveyext/editor_manual.go

@@ -15,6 +15,7 @@ type showable interface {
 	Show() error
 }
 
+// Edit opens the given content in a text editor and returns the result.
 func Edit(editorCommand, fn, initialValue string, stdin io.Reader, stdout io.Writer, stderr io.Writer) (string, error) {
 	return edit(editorCommand, fn, initialValue, stdin, stdout, stderr, nil, defaultLookPath)
 }

test/helpers.go

@@ -12,10 +12,12 @@ type CmdOut struct {
 	BrowsedURL string
 }
 
+// String returns the string representation of CmdOut.
 func (c CmdOut) String() string {
 	return c.OutBuf.String()
 }
 
+// Stderr performs the Stderr operation on CmdOut.
 func (c CmdOut) Stderr() string {
 	return c.ErrBuf.String()
 }
@@ -26,6 +28,7 @@ type OutputStub struct {
 	Error error
 }
 
+// Output runs the OutputStub and returns its output.
 func (s OutputStub) Output() ([]byte, error) {
 	if s.Error != nil {
 		return s.Out, s.Error
@@ -33,6 +36,7 @@ func (s OutputStub) Output() ([]byte, error) {
 	return s.Out, nil
 }
 
+// Run executes the OutputStub command.
 func (s OutputStub) Run() error {
 	if s.Error != nil {
 		return s.Error
@@ -40,6 +44,7 @@ func (s OutputStub) Run() error {
 	return nil
 }
 
+// T defines the interface for t.
 type T interface {
 	Helper()
 	Errorf(string, ...interface{})

utils/utils.go

@@ -7,6 +7,7 @@ import (
 	"golang.org/x/term"
 )
 
+// IsDebugEnabled reports whether debug mode is active.
 func IsDebugEnabled() (bool, string) {
 	debugValue, isDebugSet := os.LookupEnv("GH_DEBUG")
 	legacyDebugValue := os.Getenv("DEBUG")
@@ -28,6 +29,7 @@ func IsDebugEnabled() (bool, string) {
 	}
 }
 
+// TerminalSize returns the width and height of the terminal.
 var TerminalSize = func(w interface{}) (int, int, error) {
 	if f, isFile := w.(*os.File); isFile {
 		return term.GetSize(int(f.Fd()))