From 3316d2ebc77cef2c2bd03869063910bd8453d704 Mon Sep 17 00:00:00 2001
From: Felix Hanley <felix@userspace.com.au>
Date: Wed, 14 Jan 2026 09:46:25 +1100
Subject: Update docs and examples

---
 README.md       | 19 +++++++++++++------
 example.go      | 22 ----------------------
 example_test.go | 29 +++++++++++++++++++++++++++++
 flag.go         | 16 ++++++++++++++--
 4 files changed, 56 insertions(+), 30 deletions(-)
 delete mode 100644 example.go
 create mode 100644 example_test.go

diff --git a/README.md b/README.md
index 1929ec4..fe1e220 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,23 @@
 # Environment variables and flags
 
-Set flags using Go's `flag` package, and complement them with environment 
-variables. Flags, if set, take precedence over the environment.
+Set flags using the standard library `flag` package, and complement them with 
+environment variables.
 
-Go's standard `flag.FlagSet` can be initialised as normal and parse errors are 
-returned as expected. Environment variables can have custom prefixes, suffixes 
-etc. as can the usage displayed with the standard `-h` flag.
+- All Go's standard `flag` functions are used as normal and parse errors are
+  returned as expected.
+
+- Flags, if set, take precedence over the environment.
+
+- Environment variables can have custom prefixes and suffixes.
+
+- Usage output can be displayed with the standard `-h` flag.
+
+- Usage output can be annotated with the configured environment variables.
 
 ```go
 fs := flag.NewFlagSet("test", flag.ContinueOnError)
 fs.String("db", "", "Database thing")
-envflag.ParseFlagSet(fs, envflag.Prefix("APP_"), envflag.UsageSuffixer())
+_ = envflag.ParseFlagSet(fs, envflag.Prefix("APP_"), envflag.UsageSuffixer())
 ```
 
 produces the following usage
diff --git a/example.go b/example.go
deleted file mode 100644
index a5c459f..0000000
--- a/example.go
+++ /dev/null
@@ -1,22 +0,0 @@
-package envflag
-
-import (
-	"flag"
-	"os"
-)
-
-func ExampleFlag() {
-	flag.Bool("verbose", false, "Be verbose")
-	Parse()
-}
-
-func ExampleFlagSet() {
-	fs := flag.NewFlagSet("example", flag.ExitOnError)
-	fs.Bool("verbose", false, "Be verbose")
-	ParseFlagSet(fs, os.Args[1:])
-}
-
-func ExamplePrefix() {
-	flag.String("db", "", "Database thing")
-	Parse(Prefix("APP_"))
-}
diff --git a/example_test.go b/example_test.go
new file mode 100644
index 0000000..349a36b
--- /dev/null
+++ b/example_test.go
@@ -0,0 +1,29 @@
+package envflag_test
+
+import (
+	"flag"
+	"os"
+
+	"userspace.com.au/envflag"
+)
+
+func ExampleFlag() {
+	flag.Bool("verbose", false, "Be verbose")
+	envflag.Parse()
+}
+
+func ExampleFlagSet() {
+	fs := flag.NewFlagSet("example", flag.ExitOnError)
+	fs.Bool("verbose", false, "Be verbose")
+	_ = envflag.ParseFlagSet(fs, os.Args[1:], envflag.UsageSuffixer())
+}
+
+func ExamplePrefix() {
+	flag.String("db", "", "Database thing")
+	_ = envflag.Parse(envflag.Prefix("APP_"))
+}
+
+func ExampleUsageSuffixer() {
+	flag.String("db", "", "Database thing")
+	_ = envflag.Parse(envflag.Prefix("APP_"))
+}
diff --git a/flag.go b/flag.go
index faa37d8..bef83d7 100644
--- a/flag.go
+++ b/flag.go
@@ -20,7 +20,7 @@ type UsageUpdaterFunc func(key, usage string) string
 
 type config struct {
 	prefix        string
-	getenv func(string) string
+	getenv        func(string) string
 	flagConverter FlagConverterFunc
 	usageUpdater  UsageUpdaterFunc
 }
@@ -55,6 +55,12 @@ func UsageUpdater(f UsageUpdaterFunc) Option {
 }
 
 // UsagePrefixer prefixes the flag usage with [envvar].
+//
+// Example output:
+//
+//	Usage of example:
+//	  -verbose
+//	        [VERBOSE] Be verbose
 func UsagePrefixer() Option {
 	return func(cfg *config) {
 		cfg.usageUpdater = usagePrefixer
@@ -62,6 +68,12 @@ func UsagePrefixer() Option {
 }
 
 // UsageSuffixer suffixes the flag usage with [envvar].
+//
+// Example output:
+//
+//	Usage of example:
+//	  -verbose
+//	        Be verbose [VERBOSE]
 func UsageSuffixer() Option {
 	return func(cfg *config) {
 		cfg.usageUpdater = usageSuffixer
@@ -88,7 +100,7 @@ func parseFlagSetWithEnv(fs *flag.FlagSet, arguments []string, opts ...Option) e
 	}
 	cfg := &config{
 		flagConverter: flagToEnv(),
-		getenv: os.Getenv,
+		getenv:        os.Getenv,
 	}
 	for _, o := range opts {
 		o(cfg)
-- 
cgit v1.2.3