From b13a62172a12a2b2f0cfd7eeed10d846845a5f77 Mon Sep 17 00:00:00 2001
From: Alex Flint <alex.flint@gmail.com>
Date: Thu, 5 Sep 2024 17:15:02 -0400
Subject: [PATCH] update api docs for Parser.Parse

---
 README.md | 14 ++++----------
 parse.go  |  9 ++++++++-
 2 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 9b8b071..761af56 100644
--- a/README.md
+++ b/README.md
@@ -582,7 +582,7 @@ if p.Subcommand() == nil {
 ```
 
 
-### Programmatic error handling
+### Custom handling of --help and --version
 
 The following reproduces the internal logic of `MustParse` for the simple case where
 you are not using subcommands or --version. This allows you to respond
@@ -625,9 +625,6 @@ Usage: ./example --something SOMETHING
 $ ./example
 error: --something is required
 Usage: ./example --something SOMETHING
-
-$ ./example --something abc
-got "abc"
 ```
 
 To also handle --version programatically, use the following:
@@ -686,13 +683,10 @@ Usage: example --something SOMETHING
 $ ./example
 error: --something is required
 Usage: example --something SOMETHING
-
-$ ./example --something abc
-got "abc"
 ```
 
-To also handle subcommands, use this most general version (also works in absence of subcommands but
-is a bit more complex):
+To generate subcommand-specific help messages, use the following most general version
+(this also works in absence of subcommands but is a bit more complex):
 
 ```go
 type fetchCmd struct {
@@ -761,7 +755,7 @@ Global options:
 
 ### API Documentation
 
-https://godoc.org/github.com/alexflint/go-arg
+https://pkg.go.dev/github.com/alexflint/go-arg
 
 ### Rationale
 
diff --git a/parse.go b/parse.go
index 2bed8bf..8f99a21 100644
--- a/parse.go
+++ b/parse.go
@@ -494,7 +494,14 @@ func cmdFromStruct(name string, dest path, t reflect.Type) (*command, error) {
 }
 
 // Parse processes the given command line option, storing the results in the field
-// of the structs from which NewParser was constructed
+// of the structs from which NewParser was constructed.
+//
+// It returns ErrHelp if "--help" is one of the command line args and ErrVersion if
+// "--version" is one of the command line args (the latter only applies if the
+// destination struct passed to NewParser implements Versioned.)
+//
+// To respond to --help and --version in the way that MustParse does, see examples
+// in the README under "Custom handling of --help and --version".
 func (p *Parser) Parse(args []string) error {
 	err := p.process(args)
 	if err != nil {