From f8cbbedc38513eab358e4730cc53abfdefab3fb1 Mon Sep 17 00:00:00 2001
From: Billie Cleek <bhcleek@gmail.com>
Date: Fri, 8 Mar 2024 12:50:19 -0800
Subject: [PATCH] docs: document how backquotes are handled in usage messages

---
 flag.go | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/flag.go b/flag.go
index 7c058de3..eb2c8b81 100644
--- a/flag.go
+++ b/flag.go
@@ -527,7 +527,8 @@ func Set(name, value string) error {
 }
 
 // PrintDefaults prints, to standard error unless configured
-// otherwise, the default values of all defined flags in the set.
+// otherwise, the default values of all defined flags in the set. See the
+// documentation for the global function PrintDefaults for more information.
 func (f *FlagSet) PrintDefaults() {
 	usages := f.FlagUsages()
 	fmt.Fprint(f.Output(), usages)
@@ -759,6 +760,17 @@ func (f *FlagSet) FlagUsages() string {
 }
 
 // PrintDefaults prints to standard error the default values of all defined command-line flags.
+//
+// The listed type can be changed by placing a back-quoted name in the flag's
+// usage string; 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.
 func PrintDefaults() {
 	CommandLine.PrintDefaults()
 }