Add godoc comments to exported symbols in pkg/cmdutil

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

pkg/cmdutil/args.go

@@ -8,6 +8,7 @@ import (
 	"github.com/spf13/pflag"
 )
 
+// MinimumArgs returns a PositionalArgs validator that requires at least n arguments.
 func MinimumArgs(n int, msg string) cobra.PositionalArgs {
 	if msg == "" {
 		return cobra.MinimumNArgs(1)
@@ -21,6 +22,7 @@ func MinimumArgs(n int, msg string) cobra.PositionalArgs {
 	}
 }
 
+// ExactArgs returns a PositionalArgs validator that requires exactly n arguments.
 func ExactArgs(n int, msg string) cobra.PositionalArgs {
 	return func(cmd *cobra.Command, args []string) error {
 		if len(args) > n {
@@ -35,6 +37,7 @@ func ExactArgs(n int, msg string) cobra.PositionalArgs {
 	}
 }
 
+// NoArgsQuoteReminder is a PositionalArgs validator that rejects arguments with a hint to quote values containing spaces.
 func NoArgsQuoteReminder(cmd *cobra.Command, args []string) error {
 	if len(args) < 1 {
 		return nil

pkg/cmdutil/auth_check.go

@@ -10,6 +10,7 @@ import (
 
 const skipAuthCheckAnnotation = "skipAuthCheck"
 
+// DisableAuthCheck annotates a command so that it skips the authentication check.
 func DisableAuthCheck(cmd *cobra.Command) {
 	if cmd.Annotations == nil {
 		cmd.Annotations = map[string]string{}
@@ -18,6 +19,7 @@ func DisableAuthCheck(cmd *cobra.Command) {
 	cmd.Annotations[skipAuthCheckAnnotation] = "true"
 }
 
+// DisableAuthCheckFlag annotates a flag so that setting it skips the authentication check.
 func DisableAuthCheckFlag(flag *pflag.Flag) {
 	if flag.Annotations == nil {
 		flag.Annotations = map[string][]string{}
@@ -26,6 +28,7 @@ func DisableAuthCheckFlag(flag *pflag.Flag) {
 	flag.Annotations[skipAuthCheckAnnotation] = []string{"true"}
 }
 
+// CheckAuth reports whether valid authentication credentials are available in the given config.
 func CheckAuth(cfg gh.Config) bool {
 	if cfg.Authentication().HasEnvToken() {
 		return true
@@ -38,6 +41,7 @@ func CheckAuth(cfg gh.Config) bool {
 	return false
 }
 
+// IsAuthCheckEnabled reports whether the authentication check should run for the given command.
 func IsAuthCheckEnabled(cmd *cobra.Command) bool {
 	switch cmd.Name() {
 	case "help", cobra.ShellCompRequestCmd, cobra.ShellCompNoDescRequestCmd:

pkg/cmdutil/cmdgroup.go

@@ -2,6 +2,7 @@ package cmdutil
 
 import "github.com/spf13/cobra"
 
+// AddGroup creates a new command group with the given title and adds the provided commands to it under the parent command.
 func AddGroup(parent *cobra.Command, title string, cmds ...*cobra.Command) {
 	g := &cobra.Group{
 		Title: title,

pkg/cmdutil/errors.go

@@ -23,10 +23,12 @@ type FlagError struct {
 	err error
 }
 
+// Error returns the underlying error message.
 func (fe *FlagError) Error() string {
 	return fe.err.Error()
 }
 
+// Unwrap returns the wrapped error.
 func (fe *FlagError) Unwrap() error {
 	return fe.err
 }
@@ -40,10 +42,12 @@ var CancelError = errors.New("CancelError")
 // PendingError signals nothing failed but something is pending
 var PendingError = errors.New("PendingError")
 
+// IsUserCancellation reports whether err indicates that the user cancelled the operation.
 func IsUserCancellation(err error) bool {
 	return errors.Is(err, CancelError) || errors.Is(err, terminal.InterruptErr)
 }
 
+// MutuallyExclusive returns a FlagError with the given message if more than one of the conditions is true.
 func MutuallyExclusive(message string, conditions ...bool) error {
 	numTrue := 0
 	for _, ok := range conditions {
@@ -57,14 +61,17 @@ func MutuallyExclusive(message string, conditions ...bool) error {
 	return nil
 }
 
+// NoResultsError represents an error indicating that a query returned no results.
 type NoResultsError struct {
 	message string
 }
 
+// Error returns the no-results message.
 func (e NoResultsError) Error() string {
 	return e.message
 }
 
+// NewNoResultsError creates a NoResultsError with the given message.
 func NewNoResultsError(message string) NoResultsError {
 	return NoResultsError{message: message}
 }

pkg/cmdutil/factory.go

@@ -16,6 +16,7 @@ import (
 	"github.com/cli/cli/v2/pkg/iostreams"
 )
 
+// Factory provides common dependencies for command constructors.
 type Factory struct {
 	AppVersion     string
 	ExecutableName string

pkg/cmdutil/file_input.go

@@ -5,6 +5,7 @@ import (
 	"os"
 )
 
+// ReadFile reads the contents of filename, or from stdin if filename is "-".
 func ReadFile(filename string, stdin io.ReadCloser) ([]byte, error) {
 	if filename == "-" {
 		b, err := io.ReadAll(stdin)

pkg/cmdutil/flags.go

@@ -35,6 +35,7 @@ func StringEnumFlag(cmd *cobra.Command, p *string, name, shorthand, defaultValue
 	return f
 }
 
+// StringSliceEnumFlag defines a new string-slice flag that only allows values listed in options.
 func StringSliceEnumFlag(cmd *cobra.Command, p *[]string, name, shorthand string, defaultValues, options []string, usage string) *pflag.Flag {
 	*p = defaultValues
 	val := &enumMultiValue{value: p, options: options}
@@ -77,11 +78,13 @@ func newStringValue(p **string) *stringValue {
 	return &stringValue{p}
 }
 
+// Set assigns the string value.
 func (s *stringValue) Set(value string) error {
 	*s.string = &value
 	return nil
 }
 
+// String returns the current string value or an empty string if unset.
 func (s *stringValue) String() string {
 	if s.string == nil || *s.string == nil {
 		return ""
@@ -89,6 +92,7 @@ func (s *stringValue) String() string {
 	return **s.string
 }
 
+// Type returns the flag type name "string".
 func (s *stringValue) Type() string {
 	return "string"
 }
@@ -101,12 +105,14 @@ func newBoolValue(p **bool) *boolValue {
 	return &boolValue{p}
 }
 
+// Set parses and assigns the boolean value.
 func (b *boolValue) Set(value string) error {
 	v, err := strconv.ParseBool(value)
 	*b.bool = &v
 	return err
 }
 
+// String returns the current boolean value as a string.
 func (b *boolValue) String() string {
 	if b.bool == nil || *b.bool == nil {
 		return "false"
@@ -116,10 +122,12 @@ func (b *boolValue) String() string {
 	return "false"
 }
 
+// Type returns the flag type name "bool".
 func (b *boolValue) Type() string {
 	return "bool"
 }
 
+// IsBoolFlag returns true, indicating this flag does not require an argument.
 func (b *boolValue) IsBoolFlag() bool {
 	return true
 }
@@ -129,6 +137,7 @@ type enumValue struct {
 	options []string
 }
 
+// Set validates and assigns the value, returning an error if it is not in the allowed options.
 func (e *enumValue) Set(value string) error {
 	if !isIncluded(value, e.options) {
 		return fmt.Errorf("valid values are %s", formatValuesForUsageDocs(e.options))
@@ -137,10 +146,12 @@ func (e *enumValue) Set(value string) error {
 	return nil
 }
 
+// String returns the current enum value.
 func (e *enumValue) String() string {
 	return *e.string
 }
 
+// Type returns the flag type name "string".
 func (e *enumValue) Type() string {
 	return "string"
 }
@@ -150,6 +161,7 @@ type enumMultiValue struct {
 	options []string
 }
 
+// Set validates and appends comma-separated values, returning an error if any value is not in the allowed options.
 func (e *enumMultiValue) Set(value string) error {
 	items := strings.Split(value, ",")
 	for _, item := range items {
@@ -161,6 +173,7 @@ func (e *enumMultiValue) Set(value string) error {
 	return nil
 }
 
+// String returns the current values formatted as a brace-enclosed, comma-separated list.
 func (e *enumMultiValue) String() string {
 	if len(*e.value) == 0 {
 		return ""
@@ -168,6 +181,7 @@ func (e *enumMultiValue) String() string {
 	return fmt.Sprintf("{%s}", strings.Join(*e.value, ", "))
 }
 
+// Type returns the flag type name "stringSlice".
 func (e *enumMultiValue) Type() string {
 	return "stringSlice"
 }

pkg/cmdutil/json_flags.go

@@ -19,10 +19,12 @@ import (
 	"github.com/spf13/pflag"
 )
 
+// JSONFlagError wraps an error related to JSON flag validation.
 type JSONFlagError struct {
 	error
 }
 
+// AddJSONFlags registers --json, --jq, and --template flags on the command.
 func AddJSONFlags(cmd *cobra.Command, exportTarget *Exporter, fields []string) {
 	f := cmd.Flags()
 	addJsonFlag(f)
@@ -32,6 +34,7 @@ func AddJSONFlags(cmd *cobra.Command, exportTarget *Exporter, fields []string) {
 	setupJsonFlags(cmd, exportTarget, fields)
 }
 
+// AddJSONFlagsWithoutShorthand registers --json, --jq, and --template flags without short-hand aliases.
 func AddJSONFlagsWithoutShorthand(cmd *cobra.Command, exportTarget *Exporter, fields []string) {
 	f := cmd.Flags()
 	addJsonFlag(f)
@@ -143,6 +146,7 @@ func checkJSONFlags(cmd *cobra.Command) (*jsonExporter, error) {
 	return nil, nil
 }
 
+// AddFormatFlags registers --format, --jq, and --template flags on the command.
 func AddFormatFlags(cmd *cobra.Command, exportTarget *Exporter) {
 	var format string
 	StringEnumFlag(cmd, &format, "format", "", "", []string{"json"}, "Output format")
@@ -195,6 +199,7 @@ func checkFormatFlags(cmd *cobra.Command) (*jsonExporter, error) {
 	return nil, nil
 }
 
+// Exporter defines methods for writing structured output from commands.
 type Exporter interface {
 	Fields() []string
 	Write(io *iostreams.IOStreams, data interface{}) error
@@ -211,10 +216,12 @@ func NewJSONExporter() *jsonExporter {
 	return &jsonExporter{}
 }
 
+// Fields returns the list of field names to export.
 func (e *jsonExporter) Fields() []string {
 	return e.fields
 }
 
+// SetFields sets the list of field names to export.
 func (e *jsonExporter) SetFields(fields []string) {
 	e.fields = fields
 }

pkg/cmdutil/repo_override.go

@@ -19,6 +19,7 @@ func executeParentHooks(cmd *cobra.Command, args []string) error {
 	return nil
 }
 
+// EnableRepoOverride adds a --repo flag to the command and configures the factory to use it.
 func EnableRepoOverride(cmd *cobra.Command, f *Factory) {
 	cmd.PersistentFlags().StringP("repo", "R", "", "Select another repository using the `[HOST/]OWNER/REPO` format")
 	_ = cmd.RegisterFlagCompletionFunc("repo", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
@@ -57,6 +58,7 @@ func EnableRepoOverride(cmd *cobra.Command, f *Factory) {
 	}
 }
 
+// OverrideBaseRepoFunc returns a BaseRepo function that resolves to the override repository when set.
 func OverrideBaseRepoFunc(f *Factory, override string) func() (ghrepo.Interface, error) {
 	if override == "" {
 		override = os.Getenv("GH_REPO")