From 0f056af21f5f368e5b0646079d0094a2c64150f7 Mon Sep 17 00:00:00 2001 From: Oleg Atamanenko Date: Tue, 24 Jan 2017 11:30:45 -0500 Subject: [PATCH] Added godocs to public methods. (#386) * Added godocs to public methods. * Fix gofmt formatting. --- bash_completions.go | 3 +++ cobra.go | 3 ++- command.go | 54 ++++++++++++++++++++++++++++----------------- 3 files changed, 39 insertions(+), 21 deletions(-) diff --git a/bash_completions.go b/bash_completions.go index 7a5bd4d7..59b55068 100644 --- a/bash_completions.go +++ b/bash_completions.go @@ -10,6 +10,7 @@ import ( "github.com/spf13/pflag" ) +// Annotations for Bash completion. const ( BashCompFilenameExt = "cobra_annotation_bash_completion_filename_extensions" BashCompCustom = "cobra_annotation_bash_completion_custom" @@ -566,6 +567,7 @@ func gen(cmd *Command, w io.Writer) error { return nil } +// GenBashCompletion generates bash completion file and writes to the passed writer. func (cmd *Command) GenBashCompletion(w io.Writer) error { if err := preamble(w, cmd.Name()); err != nil { return err @@ -585,6 +587,7 @@ func nonCompletableFlag(flag *pflag.Flag) bool { return flag.Hidden || len(flag.Deprecated) > 0 } +// GenBashCompletionFile generates bash completion file. func (cmd *Command) GenBashCompletionFile(filename string) error { outFile, err := os.Create(filename) if err != nil { diff --git a/cobra.go b/cobra.go index b39c715a..9605b984 100644 --- a/cobra.go +++ b/cobra.go @@ -37,7 +37,8 @@ var templateFuncs = template.FuncMap{ var initializers []func() -// Automatic prefix matching can be a dangerous thing to automatically enable in CLI tools. +// EnablePrefixMatching allows to set automatic prefix matching. Automatic prefix matching can be a dangerous thing +// to automatically enable in CLI tools. // Set this to true to enable it. var EnablePrefixMatching = false diff --git a/command.go b/command.go index 49889318..3ee1a0a9 100644 --- a/command.go +++ b/command.go @@ -129,7 +129,7 @@ type Command struct { DisableFlagParsing bool } -// os.Args[1:] by default, if desired, can be overridden +// SetArgs sets arguments for the command. It is set to os.Args[1:] by default, if desired, can be overridden // particularly useful when testing. func (c *Command) SetArgs(a []string) { c.args = a @@ -141,12 +141,12 @@ func (c *Command) SetOutput(output io.Writer) { c.output = &output } -// Usage can be defined by application. +// SetUsageFunc sets usage function. Usage can be defined by application. func (c *Command) SetUsageFunc(f func(*Command) error) { c.usageFunc = f } -// Can be defined by Application. +// SetUsageTemplate sets usage template. Can be defined by Application. func (c *Command) SetUsageTemplate(s string) { c.usageTemplate = s } @@ -157,16 +157,17 @@ func (c *Command) SetFlagErrorFunc(f func(*Command, error) error) { c.flagErrorFunc = f } -// Can be defined by Application +// SetHelpFunc sets help function. Can be defined by Application func (c *Command) SetHelpFunc(f func(*Command, []string)) { c.helpFunc = f } +// SetHelpCommand sets help command. func (c *Command) SetHelpCommand(cmd *Command) { c.helpCommand = cmd } -// Can be defined by Application. +// SetHelpTemplate sets help template to be used. Application can use it to set custom template. func (c *Command) SetHelpTemplate(s string) { c.helpTemplate = s } @@ -183,10 +184,12 @@ func (c *Command) SetGlobalNormalizationFunc(n func(f *flag.FlagSet, name string } } +// OutOrStdout returns output to stdout func (c *Command) OutOrStdout() io.Writer { return c.getOut(os.Stdout) } +// OutOrStderr returns output to stderr func (c *Command) OutOrStderr() io.Writer { return c.getOut(os.Stderr) } @@ -265,6 +268,7 @@ func (c *Command) Help() error { return nil } +// UsageString return usage string. func (c *Command) UsageString() string { tmpOutput := c.output bb := new(bytes.Buffer) @@ -292,6 +296,7 @@ func (c *Command) FlagErrorFunc() (f func(*Command, error) error) { var minUsagePadding = 25 +// UsagePadding return padding for the usage. func (c *Command) UsagePadding() int { if c.parent == nil || minUsagePadding > c.parent.commandsMaxUseLen { return minUsagePadding @@ -301,7 +306,7 @@ func (c *Command) UsagePadding() int { var minCommandPathPadding = 11 -// +// CommandPathPadding return padding for the command path. func (c *Command) CommandPathPadding() int { if c.parent == nil || minCommandPathPadding > c.parent.commandsMaxCommandPathLen { return minCommandPathPadding @@ -311,6 +316,7 @@ func (c *Command) CommandPathPadding() int { var minNamePadding = 11 +// NamePadding returns padding for the name. func (c *Command) NamePadding() int { if c.parent == nil || minNamePadding > c.parent.commandsMaxNameLen { return minNamePadding @@ -318,6 +324,7 @@ func (c *Command) NamePadding() int { return c.parent.commandsMaxNameLen } +// UsageTemplate returns usage template for the command. func (c *Command) UsageTemplate() string { if c.usageTemplate != "" { return c.usageTemplate @@ -353,6 +360,7 @@ Use "{{.CommandPath}} [command] --help" for more information about a command.{{e ` } +// HelpTemplate return help template for the command. func (c *Command) HelpTemplate() string { if c.helpTemplate != "" { return c.helpTemplate @@ -418,7 +426,7 @@ func stripFlags(args []string, c *Command) []string { case inFlag: inFlag = false case y == "": - // strip empty commands, as the go tests expect this to be ok.... + // strip empty commands, as the go tests expect this to be ok.... case !strings.HasPrefix(y, "-"): commands = append(commands, y) inFlag = false @@ -447,7 +455,7 @@ func argsMinusFirstX(args []string, x string) []string { return args } -// find the target command given the args and command tree +// Find finds the target command given the args and command tree // Meant to be run on the highest node. Only searches down. func (c *Command) Find(args []string) (*Command, []string, error) { if c == nil { @@ -515,6 +523,7 @@ func (c *Command) Find(args []string) (*Command, []string, error) { return commandFound, a, nil } +// SuggestionsFor provides suggestions for the typedName. func (c *Command) SuggestionsFor(typedName string) []string { suggestions := []string{} for _, cmd := range c.commands { @@ -535,6 +544,7 @@ func (c *Command) SuggestionsFor(typedName string) []string { return suggestions } +// VisitParents visits all parents of the command and invokes fn on each parent. func (c *Command) VisitParents(fn func(*Command)) { var traverse func(*Command) *Command @@ -550,6 +560,7 @@ func (c *Command) VisitParents(fn func(*Command)) { traverse(c) } +// Root finds root command. func (c *Command) Root() *Command { var findRoot func(*Command) *Command @@ -674,7 +685,7 @@ func (c *Command) errorMsgFromParse() string { return "" } -// Call execute to use the args (os.Args[1:] by default) +// Execute Call execute to use the args (os.Args[1:] by default) // and run through the command tree finding appropriate matches // for commands and then corresponding flags. func (c *Command) Execute() error { @@ -682,6 +693,7 @@ func (c *Command) Execute() error { return err } +// ExecuteC executes the command. func (c *Command) ExecuteC() (cmd *Command, err error) { // Regardless of what command execute is called on, run on Root only @@ -779,7 +791,7 @@ func (c *Command) initHelpCmd() { c.AddCommand(c.helpCommand) } -// Used for testing. +// ResetCommands used for testing. func (c *Command) ResetCommands() { c.commands = nil c.helpCommand = nil @@ -902,7 +914,7 @@ func (c *Command) UseLine() string { return str + c.Use } -// For use in determining which flags have been assigned to which commands +// DebugFlags used to determine which flags have been assigned to which commands // and which persist. func (c *Command) DebugFlags() { c.Println("DebugFlags called on", c.Name()) @@ -970,10 +982,12 @@ func (c *Command) HasAlias(s string) bool { return false } +// NameAndAliases returns string containing name and all aliases func (c *Command) NameAndAliases() string { return strings.Join(append([]string{c.Name()}, c.Aliases...), ", ") } +// HasExample determines if the command has example. func (c *Command) HasExample() bool { return len(c.Example) > 0 } @@ -1070,7 +1084,7 @@ func (c *Command) GlobalNormalizationFunc() func(f *flag.FlagSet, name string) f return c.globNormFunc } -// Flage returns the complete FlagSet that applies +// Flags returns the complete FlagSet that applies // to this command (local and persistent declared here and by all parents). func (c *Command) Flags() *flag.FlagSet { if c.flags == nil { @@ -1170,44 +1184,44 @@ func (c *Command) ResetFlags() { c.pflags.SetOutput(c.flagErrorBuf) } -// Does the command contain any flags (local plus persistent from the entire structure). +// HasFlags checks if the command contains any flags (local plus persistent from the entire structure). func (c *Command) HasFlags() bool { return c.Flags().HasFlags() } -// Does the command contain persistent flags. +// HasPersistentFlags checks if the command contains persistent flags. func (c *Command) HasPersistentFlags() bool { return c.PersistentFlags().HasFlags() } -// Does the command has flags specifically declared locally. +// HasLocalFlags checks if the command has flags specifically declared locally. func (c *Command) HasLocalFlags() bool { return c.LocalFlags().HasFlags() } -// Does the command have flags inherited from its parent command. +// HasInheritedFlags checks if the command has flags inherited from its parent command. func (c *Command) HasInheritedFlags() bool { return c.InheritedFlags().HasFlags() } -// Does the command contain any flags (local plus persistent from the entire +// HasAvailableFlags checks if the command contains any flags (local plus persistent from the entire // structure) which are not hidden or deprecated. func (c *Command) HasAvailableFlags() bool { return c.Flags().HasAvailableFlags() } -// Does the command contain persistent flags which are not hidden or deprecated. +// HasAvailablePersistentFlags checks if the command contains persistent flags which are not hidden or deprecated. func (c *Command) HasAvailablePersistentFlags() bool { return c.PersistentFlags().HasAvailableFlags() } -// Does the command has flags specifically declared locally which are not hidden +// HasAvailableLocalFlags checks if the command has flags specifically declared locally which are not hidden // or deprecated. func (c *Command) HasAvailableLocalFlags() bool { return c.LocalFlags().HasAvailableFlags() } -// Does the command have flags inherited from its parent command which are +// HasAvailableInheritedFlags checks if the command has flags inherited from its parent command which are // not hidden or deprecated. func (c *Command) HasAvailableInheritedFlags() bool { return c.InheritedFlags().HasAvailableFlags()