Merge pull request #46 from eparis/goreportcard

Fix up minor things found by goreportcard.com

1 files changed, 114 insertions, 93 deletions

diff --git a/flag.go b/flag.go
index 6695472..81b3c1f 100644
--- a/flag.go
+++ b/flag.go
@@ -3,98 +3,98 @@
 // license that can be found in the LICENSE file.
 
 /*
-	pflag is a drop-in replacement for Go's flag package, implementing
-	POSIX/GNU-style --flags.
+Package pflag is a drop-in replacement for Go's flag package, implementing
+POSIX/GNU-style --flags.
 
-	pflag is compatible with the GNU extensions to the POSIX recommendations
-	for command-line options. See
-	http://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html
+pflag is compatible with the GNU extensions to the POSIX recommendations
+for command-line options. See
+http://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html
 
-	Usage:
+Usage:
 
-	pflag is a drop-in replacement of Go's native flag package. If you import
-	pflag under the name "flag" then all code should continue to function
-	with no changes.
+pflag is a drop-in replacement of Go's native flag package. If you import
+pflag under the name "flag" then all code should continue to function
+with no changes.
 
-		import flag "github.com/ogier/pflag"
+	import flag "github.com/ogier/pflag"
 
 	There is one exception to this: if you directly instantiate the Flag struct
-	there is one more field "Shorthand" that you will need to set.
-	Most code never instantiates this struct directly, and instead uses
-	functions such as String(), BoolVar(), and Var(), and is therefore
-	unaffected.
-
-	Define flags using flag.String(), Bool(), Int(), etc.
-
-	This declares an integer flag, -flagname, stored in the pointer ip, with type *int.
-		var ip = flag.Int("flagname", 1234, "help message for flagname")
-	If you like, you can bind the flag to a variable using the Var() functions.
-		var flagvar int
-		func init() {
-			flag.IntVar(&flagvar, "flagname", 1234, "help message for flagname")
-		}
-	Or you can create custom flags that satisfy the Value interface (with
-	pointer receivers) and couple them to flag parsing by
-		flag.Var(&flagVal, "name", "help message for flagname")
-	For such flags, the default value is just the initial value of the variable.
-
-	After all flags are defined, call
-		flag.Parse()
-	to parse the command line into the defined flags.
-
-	Flags may then be used directly. If you're using the flags themselves,
-	they are all pointers; if you bind to variables, they're values.
-		fmt.Println("ip has value ", *ip)
-		fmt.Println("flagvar has value ", flagvar)
-
-	After parsing, the arguments after the flag are available as the
-	slice flag.Args() or individually as flag.Arg(i).
-	The arguments are indexed from 0 through flag.NArg()-1.
-
-	The pflag package also defines some new functions that are not in flag,
-	that give one-letter shorthands for flags. You can use these by appending
-	'P' to the name of any function that defines a flag.
-		var ip = flag.IntP("flagname", "f", 1234, "help message")
-		var flagvar bool
-		func init() {
-			flag.BoolVarP("boolname", "b", true, "help message")
-		}
-		flag.VarP(&flagVar, "varname", "v", 1234, "help message")
-	Shorthand letters can be used with single dashes on the command line.
-	Boolean shorthand flags can be combined with other shorthand flags.
-
-	Command line flag syntax:
-		--flag    // boolean flags only
-		--flag=x
-
-	Unlike the flag package, a single dash before an option means something
-	different than a double dash. Single dashes signify a series of shorthand
-	letters for flags. All but the last shorthand letter must be boolean flags.
-		// boolean flags
-		-f
-		-abc
-		// non-boolean flags
-		-n 1234
-		-Ifile
-		// mixed
-		-abcs "hello"
-		-abcn1234
-
-	Flag parsing stops after the terminator "--". Unlike the flag package,
-	flags can be interspersed with arguments anywhere on the command line
-	before this terminator.
-
-	Integer flags accept 1234, 0664, 0x1234 and may be negative.
-	Boolean flags (in their long form) accept 1, 0, t, f, true, false,
-	TRUE, FALSE, True, False.
-	Duration flags accept any input valid for time.ParseDuration.
-
-	The default set of command-line flags is controlled by
-	top-level functions.  The FlagSet type allows one to define
-	independent sets of flags, such as to implement subcommands
-	in a command-line interface. The methods of FlagSet are
-	analogous to the top-level functions for the command-line
-	flag set.
+there is one more field "Shorthand" that you will need to set.
+Most code never instantiates this struct directly, and instead uses
+functions such as String(), BoolVar(), and Var(), and is therefore
+unaffected.
+
+Define flags using flag.String(), Bool(), Int(), etc.
+
+This declares an integer flag, -flagname, stored in the pointer ip, with type *int.
+	var ip = flag.Int("flagname", 1234, "help message for flagname")
+If you like, you can bind the flag to a variable using the Var() functions.
+	var flagvar int
+	func init() {
+		flag.IntVar(&flagvar, "flagname", 1234, "help message for flagname")
+	}
+Or you can create custom flags that satisfy the Value interface (with
+pointer receivers) and couple them to flag parsing by
+	flag.Var(&flagVal, "name", "help message for flagname")
+For such flags, the default value is just the initial value of the variable.
+
+After all flags are defined, call
+	flag.Parse()
+to parse the command line into the defined flags.
+
+Flags may then be used directly. If you're using the flags themselves,
+they are all pointers; if you bind to variables, they're values.
+	fmt.Println("ip has value ", *ip)
+	fmt.Println("flagvar has value ", flagvar)
+
+After parsing, the arguments after the flag are available as the
+slice flag.Args() or individually as flag.Arg(i).
+The arguments are indexed from 0 through flag.NArg()-1.
+
+The pflag package also defines some new functions that are not in flag,
+that give one-letter shorthands for flags. You can use these by appending
+'P' to the name of any function that defines a flag.
+	var ip = flag.IntP("flagname", "f", 1234, "help message")
+	var flagvar bool
+	func init() {
+		flag.BoolVarP("boolname", "b", true, "help message")
+	}
+	flag.VarP(&flagVar, "varname", "v", 1234, "help message")
+Shorthand letters can be used with single dashes on the command line.
+Boolean shorthand flags can be combined with other shorthand flags.
+
+Command line flag syntax:
+	--flag    // boolean flags only
+	--flag=x
+
+Unlike the flag package, a single dash before an option means something
+different than a double dash. Single dashes signify a series of shorthand
+letters for flags. All but the last shorthand letter must be boolean flags.
+	// boolean flags
+	-f
+	-abc
+	// non-boolean flags
+	-n 1234
+	-Ifile
+	// mixed
+	-abcs "hello"
+	-abcn1234
+
+Flag parsing stops after the terminator "--". Unlike the flag package,
+flags can be interspersed with arguments anywhere on the command line
+before this terminator.
+
+Integer flags accept 1234, 0664, 0x1234 and may be negative.
+Boolean flags (in their long form) accept 1, 0, t, f, true, false,
+TRUE, FALSE, True, False.
+Duration flags accept any input valid for time.ParseDuration.
+
+The default set of command-line flags is controlled by
+top-level functions.  The FlagSet type allows one to define
+independent sets of flags, such as to implement subcommands
+in a command-line interface. The methods of FlagSet are
+analogous to the top-level functions for the command-line
+flag set.
 */
 package pflag
 
@@ -115,8 +115,11 @@ var ErrHelp = errors.New("pflag: help requested")
 type ErrorHandling int
 
 const (
+	// ContinueOnError will return an err from Parse() if an error is found
 	ContinueOnError ErrorHandling = iota
+	// ExitOnError will call os.Exit(2) if an error is found when parsing
 	ExitOnError
+	// PanicOnError will panic() if an error is found when parsing flags
 	PanicOnError
 )
 
@@ -181,6 +184,11 @@ func sortFlags(flags map[NormalizedName]*Flag) []*Flag {
 	return result
 }
 
+// SetNormalizeFunc allows you to add a function which can translate flag names.
+// Flags added to the FlagSet will be translated and then when anything tries to
+// look up the flag that will also be translated. So it would be possible to create
+// a flag named "getURL" and have it translated to "geturl".  A user could then pass
+// "--getUrl" which may also be translated to "geturl" and everything will work.
 func (f *FlagSet) SetNormalizeFunc(n func(f *FlagSet, name string) NormalizedName) {
 	f.normalizeNameFunc = n
 	for k, v := range f.formal {
@@ -191,6 +199,8 @@ func (f *FlagSet) SetNormalizeFunc(n func(f *FlagSet, name string) NormalizedNam
 	}
 }
 
+// GetNormalizeFunc returns the previously set NormalizeFunc of a function which
+// does no translation, if not set previously.
 func (f *FlagSet) GetNormalizeFunc() func(f *FlagSet, name string) NormalizedName {
 	if f.normalizeNameFunc != nil {
 		return f.normalizeNameFunc
@@ -224,6 +234,7 @@ func (f *FlagSet) VisitAll(fn func(*Flag)) {
 	}
 }
 
+// HasFlags returns a bool to indicate if the FlagSet has any flags definied.
 func (f *FlagSet) HasFlags() bool {
 	return len(f.formal) > 0
 }
@@ -279,7 +290,9 @@ func (f *FlagSet) getFlagType(name string, ftype string, convFunc func(sval stri
 	return result, nil
 }
 
-// Mark a flag deprecated in your program
+// MarkDeprecated indicated that a flag is deprecated in your program. It will
+// continue to function but will not show up in help or usage messages. Using
+// this flag will also print the given usageMessage.
 func (f *FlagSet) MarkDeprecated(name string, usageMessage string) error {
 	flag := f.Lookup(name)
 	if flag == nil {
@@ -317,6 +330,9 @@ func (f *FlagSet) Set(name, value string) error {
 	return nil
 }
 
+// SetAnnotation allows one to set arbitrary annotations on a flag in the FlagSet.
+// This is sometimes used by spf13/cobra programs which want to generate additional
+// bash completion information.
 func (f *FlagSet) SetAnnotation(name, key string, values []string) error {
 	normalName := f.normalizeFlagName(name)
 	flag, ok := f.formal[normalName]
@@ -330,6 +346,8 @@ func (f *FlagSet) SetAnnotation(name, key string, values []string) error {
 	return nil
 }
 
+// Changed returns true if the flag was explicitly set during Parse() and false
+// otherwise
 func (f *FlagSet) Changed(name string) bool {
 	flag := f.Lookup(name)
 	// If a flag doesn't exist, it wasn't changed....
@@ -351,6 +369,8 @@ func (f *FlagSet) PrintDefaults() {
 	fmt.Fprintf(f.out(), "%s", usages)
 }
 
+// FlagUsages Returns a string containing the usage information for all flags in
+// the FlagSet
 func (f *FlagSet) FlagUsages() string {
 	x := new(bytes.Buffer)
 
@@ -448,7 +468,7 @@ func (f *FlagSet) Var(value Value, name string, usage string) {
 	f.VarP(value, name, "", usage)
 }
 
-// Like VarP, but returns the flag created
+// VarPF is like VarP, but returns the flag created
 func (f *FlagSet) VarPF(value Value, name, shorthand, usage string) *Flag {
 	// Remember the default value as a string; it won't change.
 	flag := &Flag{
@@ -462,14 +482,15 @@ func (f *FlagSet) VarPF(value Value, name, shorthand, usage string) *Flag {
 	return flag
 }
 
-// Like Var, but accepts a shorthand letter that can be used after a single dash.
+// VarP is like Var, but accepts a shorthand letter that can be used after a single dash.
 func (f *FlagSet) VarP(value Value, name, shorthand, usage string) {
 	_ = f.VarPF(value, name, shorthand, usage)
 }
 
+// AddFlag will add the flag to the FlagSet
 func (f *FlagSet) AddFlag(flag *Flag) {
 	// Call normalizeFlagName function only once
-	var normalizedFlagName NormalizedName = f.normalizeFlagName(flag.Name)
+	normalizedFlagName := f.normalizeFlagName(flag.Name)
 
 	_, alreadythere := f.formal[normalizedFlagName]
 	if alreadythere {
@@ -513,7 +534,7 @@ func Var(value Value, name string, usage string) {
 	CommandLine.VarP(value, name, "", usage)
 }
 
-// Like Var, but accepts a shorthand letter that can be used after a single dash.
+// VarP is like Var, but accepts a shorthand letter that can be used after a single dash.
 func VarP(value Value, name, shorthand, usage string) {
 	CommandLine.VarP(value, name, shorthand, usage)
 }
@@ -706,7 +727,7 @@ func Parse() {
 	CommandLine.Parse(os.Args[1:])
 }
 
-// Whether to support interspersed option/non-option arguments.
+// SetInterspersed sets whether to support interspersed option/non-option arguments.
 func SetInterspersed(interspersed bool) {
 	CommandLine.SetInterspersed(interspersed)
 }
@@ -730,7 +751,7 @@ func NewFlagSet(name string, errorHandling ErrorHandling) *FlagSet {
 	return f
 }
 
-// Whether to support interspersed option/non-option arguments.
+// SetIntersperesed sets whether to support interspersed option/non-option arguments.
 func (f *FlagSet) SetInterspersed(interspersed bool) {
 	f.interspersed = interspersed
 }