flag: nicer usage messages

Make PrintDefaults print an easier-to-read format, and allow the user
to control it a bit by putting a hint into the usage string.

Here is the new doc comment for PrintDefaults, which does the work:

    PrintDefaults prints, to standard error unless configured otherwise, a
    usage message showing the default settings of all defined command-line
    flags. For an integer valued flag x, the default output has the form

	-x int
		usage-message-for-x (default 7)

    The usage message will appear on a separate line except for single-
    letter boolean flags. Boolean flags omit the type, since they can be
    used without an actual value, and the parenthetical default is omitted
    if the default is the zero value for the type. The type, here int, can
    be replaced by a string of the user's choosing by placing in the usage
    string for the flag a back-quoted name; the first such item in the
    message is taken to be a parameter name to show in the message and the
    back quotes are stripped from the message when displayed. For instance,
    given

	flag.String("I", "", "search `directory` for include files")

    the output will be

	-I directory
		search directory for include files.

Given

	A = flag.Bool("A", false, "for bootstrapping, allow 'any' type")
	B = flag.Bool("Alongflagname", false, "disable bounds checking")
	C = flag.Bool("C", true, "a boolean defaulting to true")
	D = flag.String("D", "", "set relative `path` for local imports")
	F = flag.Float64("F", 2.7, "a non-zero float")
	G = flag.Float64("G", 0, "a float that defaults to zero")
	N = flag.Int("N", 27, "a non-zero int")
	Z = flag.Int("Z", 0, "an int that defaults to zero")
	T = flag.Duration("deltaT", 0, "a duration")

the old output was

  -A=false: for bootstrapping, allow 'any' type
  -Alongflagname=false: disable bounds checking
  -C=true: a boolean defaulting to true
  -D="": set relative `path` for local imports
  -F=2.7: a non-zero float
  -G=0: a float that defaults to zero
  -N=27: a non-zero int
  -Z=0: an int that defaults to zero
  -deltaT=0: a duration

and the new output is

  -A	for bootstrapping, allow 'any' type
  -Alongflagname
	disable bounds checking
  -C	a boolean defaulting to true (default true)
  -D path
   	set relative path for local imports
  -F float
   	a non-zero float (default 2.7)
  -G float
   	a float that defaults to zero
  -N int
   	a non-zero int (default 27)
  -Z int
   	an int that defaults to zero
  -deltaT duration
   	a duration

Change-Id: I54ab3cd5610d551422b004d95ab78305e06a395d
Reviewed-on: https://go-review.googlesource.com/7330
Reviewed-by: Andrew Gerrand <adg@golang.org>
Reviewed-by: Russ Cox <rsc@golang.org>
2 files changed
tree: fe6240c6fec7e160fd0f3ad6ea718c64f1b391d5
  1. .gitattributes
  2. .gitignore
  3. AUTHORS
  4. CONTRIBUTING.md
  5. CONTRIBUTORS
  6. LICENSE
  7. PATENTS
  8. README.md
  9. api/
  10. doc/
  11. favicon.ico
  12. lib/
  13. misc/
  14. robots.txt
  15. src/
  16. test/
README.md

The Go Programming Language

Go is an open source programming language that makes it easy to build simple, reliable, and efficient software.

Gopher image

For documentation about how to install and use Go, visit https://golang.org/ or load doc/install-source.html in your web browser.

Our canonical Git repository is located at https://go.googlesource.com/go. There is a mirror of the repository at https://github.com/golang/go.

Please report issues here: https://golang.org/issue/new

Go is the work of hundreds of contributors. We appreciate your help!

To contribute, please read the contribution guidelines: https://golang.org/doc/contribute.html

Please note that we do not use pull requests.

Unless otherwise noted, the Go source files are distributed under the BSD-style license found in the LICENSE file.


Binary Distribution Notes

If you have just untarred a binary Go distribution, you need to set the environment variable $GOROOT to the full path of the go directory (the one containing this file). You can omit the variable if you unpack it into /usr/local/go, or if you rebuild from sources by running all.bash (see doc/install-source.html). You should also add the Go binary directory $GOROOT/bin to your shell's path.

For example, if you extracted the tar file into $HOME/go, you might put the following in your .profile:

export GOROOT=$HOME/go
export PATH=$PATH:$GOROOT/bin

See https://golang.org/doc/install or doc/install.html for more details.