Generated Documentation

powershell_completions_test.go

@@ -20,6 +20,9 @@ import (
 	"testing"
 )
 
+// TestPwshCompletionNoActiveHelp tests the generation of PowerShell completion for a command without active help.
+//
+// It creates a new Command instance with the name "c" and an empty Run function. Then, it generates PowerShell completion output using GenPowerShellCompletion method and checks if the environment variable for disabling active help is set to 0.
 func TestPwshCompletionNoActiveHelp(t *testing.T) {
 	c := &Command{Use: "c", Run: emptyRun}
 

shell_completions.go

@@ -18,23 +18,20 @@ import (
 	"github.com/spf13/pflag"
 )
 
-// MarkFlagRequired instructs the various shell completion implementations to
+// MarkFlagRequired instructs the various shell completion implementations to prioritize the named flag when performing completion, and causes your command to report an error if invoked without the flag.
-// prioritize the named flag when performing completion,
-// and causes your command to report an error if invoked without the flag.
 func (c *Command) MarkFlagRequired(name string) error {
 	return MarkFlagRequired(c.Flags(), name)
 }
 
-// MarkPersistentFlagRequired instructs the various shell completion implementations to
+// MarkPersistentFlagRequired instructs the various shell completion implementations to prioritize the named persistent flag when performing completion, and causes your command to report an error if invoked without the flag.
-// prioritize the named persistent flag when performing completion,
-// and causes your command to report an error if invoked without the flag.
 func (c *Command) MarkPersistentFlagRequired(name string) error {
 	return MarkFlagRequired(c.PersistentFlags(), name)
 }
 
-// MarkFlagRequired instructs the various shell completion implementations to
+// MarkFlagRequired instructs the various shell completion implementations to prioritize the named flag when performing completion,
-// prioritize the named flag when performing completion,
 // and causes your command to report an error if invoked without the flag.
+// It takes a pointer to a pflag.FlagSet and the name of the flag as parameters.
+// The function returns an error if setting the annotation fails.
 func MarkFlagRequired(flags *pflag.FlagSet, name string) error {
 	return flags.SetAnnotation(name, BashCompOneRequiredFlag, []string{"true"})
 }
@@ -46,11 +43,17 @@ func (c *Command) MarkFlagFilename(name string, extensions ...string) error {
 }
 
 // MarkFlagCustom adds the BashCompCustom annotation to the named flag, if it exists.
-// The bash completion script will call the bash function f for the flag.
+// The bash completion script will call the bash function `f` for the flag.
 //
-// This will only work for bash completion.
+// This will only work for bash completion. It is recommended to instead use
-// It is recommended to instead use c.RegisterFlagCompletionFunc(...) which allows
+// `c.RegisterFlagCompletionFunc(...)` which allows registering a Go function that works across all shells.
-// to register a Go function which will work across all shells.
+//
+// Parameters:
+//   - name: the name of the flag to annotate
+//   - f: the name of the bash function to call for bash completion
+//
+// Returns:
+//   - error if marking the flag fails, nil otherwise
 func (c *Command) MarkFlagCustom(name string, f string) error {
 	return MarkFlagCustom(c.Flags(), name, f)
 }
@@ -62,24 +65,40 @@ func (c *Command) MarkPersistentFlagFilename(name string, extensions ...string)
 	return MarkFlagFilename(c.PersistentFlags(), name, extensions...)
 }
 
-// MarkFlagFilename instructs the various shell completion implementations to
+// MarkFlagFilename instructs the various shell completion implementations to limit completions for the named flag to the specified file extensions.
-// limit completions for the named flag to the specified file extensions.
+//
+// Parameters:
+// - flags: A pointer to a pflag.FlagSet containing the flags.
+// - name: The name of the flag to be marked.
+// - extensions: Variable number of string arguments representing the file extensions to limit completions to.
+//
+// Returns:
+// - error: An error if setting the annotation fails, otherwise nil.
 func MarkFlagFilename(flags *pflag.FlagSet, name string, extensions ...string) error {
 	return flags.SetAnnotation(name, BashCompFilenameExt, extensions)
 }
 
 // MarkFlagCustom adds the BashCompCustom annotation to the named flag, if it exists.
-// The bash completion script will call the bash function f for the flag.
+// The bash completion script will call the bash function `f` for the flag.
 //
 // This will only work for bash completion.
 // It is recommended to instead use c.RegisterFlagCompletionFunc(...) which allows
 // to register a Go function which will work across all shells.
+//
+// Parameters:
+//   - flags: The FlagSet containing the flags.
+//   - name: The name of the flag to annotate.
+//   - f: The bash function to call for completion.
+//
+// Returns:
+//   - error if setting the annotation fails.
 func MarkFlagCustom(flags *pflag.FlagSet, name string, f string) error {
 	return flags.SetAnnotation(name, BashCompCustom, []string{f})
 }
 
 // MarkFlagDirname instructs the various shell completion implementations to
-// limit completions for the named flag to directory names.
+// limit completions for the named flag to directory names. It takes a pointer to a Command and a flag name as parameters.
+// The function calls MarkFlagDirname on the command's flags with the provided name and returns any errors encountered during the operation.
 func (c *Command) MarkFlagDirname(name string) error {
 	return MarkFlagDirname(c.Flags(), name)
 }
@@ -87,12 +106,23 @@ func (c *Command) MarkFlagDirname(name string) error {
 // MarkPersistentFlagDirname instructs the various shell completion
 // implementations to limit completions for the named persistent flag to
 // directory names.
+//
+// Parameters:
+//   - c: The command instance that contains the persistent flags.
+//   - name: The name of the persistent flag to mark.
+//
+// Returns:
+//   - error: If any error occurs during the marking process, it is returned here.
 func (c *Command) MarkPersistentFlagDirname(name string) error {
 	return MarkFlagDirname(c.PersistentFlags(), name)
 }
 
-// MarkFlagDirname instructs the various shell completion implementations to
+// MarkFlagDirname instructs the various shell completion implementations to limit completions for the named flag to directory names.
-// limit completions for the named flag to directory names.
+// Parameters:
+//   - flags: A pointer to a pflag.FlagSet containing all available flags.
+//   - name: The name of the flag to be modified.
+// Returns:
+//   - error: If an error occurs during the annotation setting, it is returned. Otherwise, nil is returned.
 func MarkFlagDirname(flags *pflag.FlagSet, name string) error {
 	return flags.SetAnnotation(name, BashCompSubdirsInDir, []string{})
 }

zsh_completions.go

@@ -21,24 +21,50 @@ import (
 	"os"
 )
 
-// GenZshCompletionFile generates zsh completion file including descriptions.
+// GenZshCompletionFile generates a zsh completion file for the command, including descriptions. It takes a filename as an argument and returns an error if any occurs during the generation process. If descriptions are included in the completion file, it calls the genZshCompletionFile method with additional parameters.
 func (c *Command) GenZshCompletionFile(filename string) error {
 	return c.genZshCompletionFile(filename, true)
 }
 
-// GenZshCompletion generates zsh completion file including descriptions
+// GenZshCompletion generates a zsh completion script for the command. It includes descriptions for each command and option,
-// and writes it to the passed writer.
+// and writes the script to the provided writer.
+//
+// Parameters:
+//   - w: io.Writer where the generated zsh completion script will be written.
+//
+// Returns:
+//   - error if there is an issue generating or writing the completion script.
+//
+// Example usage:
+//
+//     var cmd Command
+//     file, err := os.Create("completion.zsh")
+//     if err != nil {
+//         log.Fatal(err)
+//     }
+//     defer file.Close()
+//     err = cmd.GenZshCompletion(file)
+//     if err != nil {
+//         log.Fatal(err)
+//     }
 func (c *Command) GenZshCompletion(w io.Writer) error {
 	return c.genZshCompletion(w, true)
 }
 
-// GenZshCompletionFileNoDesc generates zsh completion file without descriptions.
+// GenZshCompletionFileNoDesc generates a zsh completion file without descriptions for the Command instance.
+// It takes a filename as input and returns an error if the operation fails. The function does not include descriptions in the generated file.
 func (c *Command) GenZshCompletionFileNoDesc(filename string) error {
 	return c.genZshCompletionFile(filename, false)
 }
 
-// GenZshCompletionNoDesc generates zsh completion file without descriptions
+// GenZshCompletionNoDesc generates a zsh completion file for the command without descriptions.
-// and writes it to the passed writer.
+// It writes the generated completion script to the provided writer.
+//
+// Parameters:
+//   - w: The writer to which the completion script will be written.
+//
+// Returns:
+//   - error: If an error occurs during the generation process, it will be returned.
 func (c *Command) GenZshCompletionNoDesc(w io.Writer) error {
 	return c.genZshCompletion(w, false)
 }
@@ -51,22 +77,26 @@ func (c *Command) GenZshCompletionNoDesc(w io.Writer) error {
 // To achieve file extension filtering, one can use ValidArgsFunction and
 // ShellCompDirectiveFilterFileExt.
 //
-// Deprecated
+// Deprecated: Use ShellCompDirectiveDefault or specify a valid completion function instead.
 func (c *Command) MarkZshCompPositionalArgumentFile(argPosition int, patterns ...string) error {
 	return nil
 }
 
-// MarkZshCompPositionalArgumentWords only worked for zsh. It has therefore
+// MarkZshCompPositionalArgumentWords marks the positional arguments of a command with zsh completion words.
-// been disabled.
+// This function is deprecated. For cross-shell compatibility, use ValidArgs for the first argument or ValidArgsFunction for any argument.
-// To achieve the same behavior across all shells, one can use
-// ValidArgs (for the first argument only) or ValidArgsFunction for
-// any argument (can include the first one also).
 //
-// Deprecated
+// Deprecated: Use ValidArgs or ValidArgsFunction instead.
 func (c *Command) MarkZshCompPositionalArgumentWords(argPosition int, words ...string) error {
 	return nil
 }
 
+// genZshCompletionFile generates a Zsh completion file for the command.
+//
+// It takes two parameters:
+//   - filename: The name of the file where the completion script will be written.
+//   - includeDesc: A boolean indicating whether to include descriptions in the completion script.
+//
+// It returns an error if there is an issue creating or writing to the file.
 func (c *Command) genZshCompletionFile(filename string, includeDesc bool) error {
 	outFile, err := os.Create(filename)
 	if err != nil {
@@ -77,6 +107,14 @@ func (c *Command) genZshCompletionFile(filename string, includeDesc bool) error
 	return c.genZshCompletion(outFile, includeDesc)
 }
 
+// genZshCompletion generates Zsh completion script for the command and writes it to the provided writer.
+//
+// Parameters:
+//   - w: The io.Writer where the completion script will be written.
+//   - includeDesc: A boolean indicating whether to include descriptions in the completion script.
+//
+// Returns:
+//   - error: An error if there was an issue writing to the writer or generating the script.
 func (c *Command) genZshCompletion(w io.Writer, includeDesc bool) error {
 	buf := new(bytes.Buffer)
 	genZshComp(buf, c.Name(), includeDesc)