Generated Documentation

active_help.go

@@ -33,8 +33,15 @@ const (
 // to the user.
 // The array parameter should be the array that will contain the completions.
 // This function can be called multiple times before and/or after completions are added to
-// the array.  Each time this function is called with the same array, the new
+// the array. Each time this function is called with the same array, the new
 // ActiveHelp line will be shown below the previous ones when completion is triggered.
+//
+// Parameters:
+//   - compArray: The array that will contain the completions.
+//   - activeHelpStr: The string to be added as ActiveHelp.
+//
+// Returns:
+//   - The updated array with the new ActiveHelp line appended.
 func AppendActiveHelp(compArray []Completion, activeHelpStr string) []Completion {
 	return append(compArray, fmt.Sprintf("%s%s", activeHelpMarker, activeHelpStr))
 }
@@ -44,6 +51,12 @@ func AppendActiveHelp(compArray []Completion, activeHelpStr string) []Completion
 // case, with all non-ASCII-alphanumeric characters replaced by `_`.
 // It will always return "0" if the global environment variable COBRA_ACTIVE_HELP
 // is set to "0".
+//
+// Parameters:
+//   - cmd: The root command whose ActiveHelp configuration is being retrieved.
+//
+// Returns:
+//   - A string representing the value of the ActiveHelp configuration.
 func GetActiveHelpConfig(cmd *Command) string {
 	activeHelpCfg := os.Getenv(activeHelpGlobalEnvVar)
 	if activeHelpCfg != activeHelpGlobalDisable {
@@ -52,9 +65,9 @@ func GetActiveHelpConfig(cmd *Command) string {
 	return activeHelpCfg
 }
 
-// activeHelpEnvVar returns the name of the program-specific ActiveHelp environment
-// variable.  It has the format <PROGRAM>_ACTIVE_HELP where <PROGRAM> is the name of the
-// root command in upper case, with all non-ASCII-alphanumeric characters replaced by `_`.
+// ActiveHelpEnvVar returns the name of the program-specific ActiveHelp environment variable.
+// It follows the format <PROGRAM>_ACTIVE_HELP where <PROGRAM> is the upper-case version of the root command's name,
+// with all non-ASCII-alphanumeric characters replaced by '_'.
 func activeHelpEnvVar(name string) string {
 	return configEnvVar(name, activeHelpEnvVarSuffix)
 }

active_help_test.go

@@ -26,6 +26,7 @@ const (
 	activeHelpMessage2 = "This is the rest of the activeHelp message"
 )
 
+// TestActiveHelpAlone tests that the active help function can be added to both root and child commands.
 func TestActiveHelpAlone(t *testing.T) {
 	rootCmd := &Command{
 		Use: "root",
@@ -81,6 +82,7 @@ func TestActiveHelpAlone(t *testing.T) {
 	}
 }
 
+// TestActiveHelpWithComps tests the functionality of appending active help to command completions.
 func TestActiveHelpWithComps(t *testing.T) {
 	rootCmd := &Command{
 		Use: "root",
@@ -166,6 +168,7 @@ func TestActiveHelpWithComps(t *testing.T) {
 	}
 }
 
+// TestMultiActiveHelp tests the functionality of adding multiple activeHelp messages to a command.
 func TestMultiActiveHelp(t *testing.T) {
 	rootCmd := &Command{
 		Use: "root",
@@ -228,6 +231,7 @@ func TestMultiActiveHelp(t *testing.T) {
 	}
 }
 
+// TestActiveHelpForFlag tests the functionality of adding multiple activeHelp messages to a flag completion function.
 func TestActiveHelpForFlag(t *testing.T) {
 	rootCmd := &Command{
 		Use: "root",
@@ -263,6 +267,7 @@ func TestActiveHelpForFlag(t *testing.T) {
 	}
 }
 
+// TestConfigActiveHelp tests the functionality of setting and retrieving active help configurations for a command.
 func TestConfigActiveHelp(t *testing.T) {
 	rootCmd := &Command{
 		Use: "root",
@@ -316,6 +321,7 @@ func TestConfigActiveHelp(t *testing.T) {
 	}
 }
 
+// TestDisableActiveHelp tests the disabling of active help functionality.
 func TestDisableActiveHelp(t *testing.T) {
 	rootCmd := &Command{
 		Use: "root",

args.go

@@ -21,10 +21,19 @@ import (
 
 type PositionalArgs func(cmd *Command, args []string) error
 
-// legacyArgs validation has the following behaviour:
-// - root commands with no subcommands can take arbitrary arguments
-// - root commands with subcommands will do subcommand validity checking
-// - subcommands will always accept arbitrary arguments
+// legacyArgs validates the arguments for a given command based on whether it has subcommands or not.
+//
+// Behavior:
+// - Root commands without subcommands can take arbitrary arguments.
+// - Root commands with subcommands perform subcommand-specific validity checks.
+// - Subcommands always accept arbitrary arguments.
+//
+// Parameters:
+//   - cmd: A pointer to the Command struct representing the command being checked.
+//   - args: A slice of strings representing the arguments passed to the command.
+//
+// Returns:
+//   - error: If the arguments are invalid for the given command, an error is returned. Otherwise, nil.
 func legacyArgs(cmd *Command, args []string) error {
 	// no subcommand, always take args
 	if !cmd.HasSubCommands() {
@@ -38,7 +47,11 @@ func legacyArgs(cmd *Command, args []string) error {
 	return nil
 }
 
-// NoArgs returns an error if any args are included.
+// NoArgs returns an error if any arguments are provided.
+// It checks whether the given slice of arguments `args` is empty.
+// If `args` contains elements, it indicates that unexpected arguments were provided,
+// and thus returns a formatted error indicating the unknown command and its path.
+// If no arguments are present, it returns nil, indicating successful validation.
 func NoArgs(cmd *Command, args []string) error {
 	if len(args) > 0 {
 		return fmt.Errorf("unknown command %q for %q", args[0], cmd.CommandPath())
@@ -46,8 +59,9 @@ func NoArgs(cmd *Command, args []string) error {
 	return nil
 }
 
-// OnlyValidArgs returns an error if there are any positional args that are not in
-// the `ValidArgs` field of `Command`
+// OnlyValidArgs checks if the provided arguments are valid based on the `ValidArgs` field of the given command.
+// It returns an error if any argument is not a valid option. If no validation is required, it returns nil.
+// The ValidArgs field can contain descriptions for each valid argument, which should be ignored during validation.
 func OnlyValidArgs(cmd *Command, args []string) error {
 	if len(cmd.ValidArgs) > 0 {
 		// Remove any description that may be included in ValidArgs.
@@ -65,12 +79,13 @@ func OnlyValidArgs(cmd *Command, args []string) error {
 	return nil
 }
 
-// ArbitraryArgs never returns an error.
+// ArbitraryArgs executes a command with arbitrary arguments and does not return an error.
 func ArbitraryArgs(cmd *Command, args []string) error {
 	return nil
 }
 
-// MinimumNArgs returns an error if there is not at least N args.
+// MinimumNArgs returns a PositionalArgs function that checks if there are at least N arguments provided.
+// If fewer than N arguments are given, it returns an error with a message indicating the required number of arguments and the actual count received.
 func MinimumNArgs(n int) PositionalArgs {
 	return func(cmd *Command, args []string) error {
 		if len(args) < n {
@@ -80,7 +95,8 @@ func MinimumNArgs(n int) PositionalArgs {
 	}
 }
 
-// MaximumNArgs returns an error if there are more than N args.
+// MaximumNArgs returns a PositionalArgs function that ensures no more than N arguments are provided.
+// If the number of arguments exceeds N, it returns an error indicating the maximum allowed arguments and the actual count received.
 func MaximumNArgs(n int) PositionalArgs {
 	return func(cmd *Command, args []string) error {
 		if len(args) > n {
@@ -90,7 +106,9 @@ func MaximumNArgs(n int) PositionalArgs {
 	}
 }
 
-// ExactArgs returns an error if there are not exactly n args.
+// ExactArgs returns a PositionalArgs function that checks if the command has exactly `n` arguments.
+// If the number of arguments is not exactly `n`, it returns an error with a descriptive message.
+// Otherwise, it returns nil indicating no error.
 func ExactArgs(n int) PositionalArgs {
 	return func(cmd *Command, args []string) error {
 		if len(args) != n {
@@ -101,6 +119,9 @@ func ExactArgs(n int) PositionalArgs {
 }
 
 // RangeArgs returns an error if the number of args is not within the expected range.
+// It takes two integers, min and max, representing the minimum and maximum number of arguments allowed.
+// The function returns a PositionalArgs closure that can be used as a validator for command arguments.
+// If the number of arguments does not fall within the specified range (inclusive), it returns an error with details about the expected and received argument count.
 func RangeArgs(min int, max int) PositionalArgs {
 	return func(cmd *Command, args []string) error {
 		if len(args) < min || len(args) > max {
@@ -110,7 +131,10 @@ func RangeArgs(min int, max int) PositionalArgs {
 	}
 }
 
-// MatchAll allows combining several PositionalArgs to work in concert.
+// MatchAll combines multiple PositionalArgs to work as a single PositionalArg.
+// It applies each provided PositionalArg in sequence to the command and arguments.
+// If any of the PositionalArgs return an error, that error is returned immediately.
+// If all PositionalArgs are successfully applied, nil is returned.
 func MatchAll(pargs ...PositionalArgs) PositionalArgs {
 	return func(cmd *Command, args []string) error {
 		for _, parg := range pargs {
@@ -123,9 +147,9 @@ func MatchAll(pargs ...PositionalArgs) PositionalArgs {
 }
 
 // ExactValidArgs returns an error if there are not exactly N positional args OR
-// there are any positional args that are not in the `ValidArgs` field of `Command`
+// there are any positional args that are not in the `ValidArgs` field of `Command`.
 //
-// Deprecated: use MatchAll(ExactArgs(n), OnlyValidArgs) instead
+// Deprecated: use MatchAll(ExactArgs(n), OnlyValidArgs) instead.
 func ExactValidArgs(n int) PositionalArgs {
 	return MatchAll(ExactArgs(n), OnlyValidArgs)
 }