flag: document that custom usage functions are free to call os.Exit

Some custom usage functions call it for clarity; others rely on the default
behavior, which makes an explicit call redundant. Document that it's
safe to be explicit.

Fixes #21671.

Change-Id: I08e9f47265582821cfd35995dff0c589cd85809d
Reviewed-on: https://go-review.googlesource.com/59792
Reviewed-by: Dominik Honnef <dominik@honnef.co>
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/src/flag/flag.go b/src/flag/flag.go
index 6bc8e96e209769a9e9dd75e954fc10a4f2d875e6..36e05500301cff3ff1e115d377c10e84a2de32f1 100644 (file)
--- a/src/flag/flag.go
+++ b/src/flag/flag.go
@@ -269,7 +269,9 @@ const (
 type FlagSet struct {
        // Usage is the function called when an error occurs while parsing flags.
        // The field is a function (not a method) that may be changed to point to
-       // a custom error handler.
+       // a custom error handler. What happens after Usage is called depends
+       // on the ErrorHandling setting; for the command line, this defaults
+       // to ExitOnError, which exits the program after calling Usage.
        Usage func()
 
        name          string
@@ -521,6 +523,9 @@ func (f *FlagSet) defaultUsage() {
 // The function is a variable that may be changed to point to a custom function.
 // By default it prints a simple header and calls PrintDefaults; for details about the
 // format of the output and how to control it, see the documentation for PrintDefaults.
+// Custom usage functions may choose to exit the program; by default exiting
+// happens anyway as the command line's error handling strategy is set to
+// ExitOnError.
 var Usage = func() {
        fmt.Fprintf(CommandLine.out(), "Usage of %s:\n", os.Args[0])
        PrintDefaults()