5 files changed, 95 insertions(+), 51 deletions(-)

M README.md
M complete.go
M complete_test.go
M opt.go
M spec.go

@@ 172,7 172,9 @@ func main() {
 	}
 	var s CompleteStruct
 	completions, _ := opt.GetCompletions(args.String(), &s)
-	fmt.Println(strings.Join(completions, "\n"))
+	for _, c := range completions {
+		fmt.Println(c.Value)
+	}
 }
 ```
 


@@ 237,6 239,10 @@ be a method with a pointer receiver to the struct itself, takes a single
 `string` argument and may return an `error` to abort parsing. The `action`
 method is responsible of updating the struct.
 
+### `description:"foobaz"` or `desc:"foobaz"`
+
+A description that is returned alongside arguments during autocompletion.
+
 ### `default:"foobaz"`
 
 Default `string` value if not specified by the user. Will be processed by the

@@ 5,8 5,13 @@ import (
 	"strings"
 )
 
-func (c *CmdSpec) unseenFlags(arg string) []string {
-	var flags []string
+type Completion struct {
+	Value       string
+	Description string
+}
+
+func (c *CmdSpec) unseenFlags(arg string) []Completion {
+	var flags []Completion
 	for i := 0; i < len(c.opts); i++ {
 		spec := &c.opts[i]
 		if !spec.appliesToAlias(c.name) || spec.seen {


@@ 15,10 20,16 @@ func (c *CmdSpec) unseenFlags(arg string) []string {
 		switch spec.kind {
 		case flag, option:
 			if spec.short != "" && strings.HasPrefix(spec.short, arg) {
-				flags = append(flags, spec.short+" ")
+				flags = append(flags, Completion{
+					Value:       spec.short + " ",
+					Description: spec.description,
+				})
 			}
 			if spec.long != "" && strings.HasPrefix(spec.long, arg) {
-				flags = append(flags, spec.long+" ")
+				flags = append(flags, Completion{
+					Value:       spec.long + " ",
+					Description: spec.description,
+				})
 			}
 		}
 	}


@@ 40,25 51,29 @@ func (c *CmdSpec) nextPositional() *optSpec {
 	return spec
 }
 
-func (s *optSpec) getCompletions(arg string) []string {
+func (s *optSpec) getCompletions(arg string) []Completion {
 	if s.complete.IsValid() {
 		in := []reflect.Value{reflect.ValueOf(arg)}
 		out := s.complete.Call(in)
 		if res, ok := out[0].Interface().([]string); ok {
-			return res
+			var completions []Completion
+			for _, value := range res {
+				completions = append(completions, Completion{Value: value})
+			}
+			return completions
 		}
 	}
 	return nil
 }
 
-func (c *CmdSpec) GetCompletions(args *Args) ([]string, string) {
+func (c *CmdSpec) GetCompletions(args *Args) ([]Completion, string) {
 	if args.Count() == 0 || (args.Count() == 1 && args.TrailingSpace() == "") {
 		return nil, ""
 	}
 
-	var completions []string
+	var completions []Completion
 	var prefix string
-	var flags []string
+	var flags []Completion
 	var last *seenArg
 	var spec *optSpec
 


@@ 95,7 110,7 @@ func (c *CmdSpec) GetCompletions(args *Args) ([]string, string) {
 			case (s.kind == flag || s.kind == option) && (s.short == arg || s.long == arg):
 				// Current argument is precisely a flag.
 				spec = nil
-				completions = []string{arg + " "}
+				completions = []Completion{{Value: arg + " ", Description: s.description}}
 			case s.kind == option && f != "=" && strings.HasPrefix(arg, f):
 				// Current argument is a long flag in the format:
 				//       --flag=value

@@ 11,8 11,8 @@ import (
 type CompleteStruct struct {
 	Name    string   `opt:"-n,--name" required:"true" complete:"CompleteName"`
 	Delay   float64  `opt:"--delay"`
-	Zero    bool     `opt:"-z"`
-	Backoff bool     `opt:"-B,--backoff"`
+	Zero    bool     `opt:"-z" description:"Print zero values"`
+	Backoff bool     `opt:"-B,--backoff" desc:"Increase delay on error"`
 	Tags    []string `opt:"..." complete:"CompleteTag"`
 }
 


@@ 47,93 47,105 @@ func (c *CompleteStruct) CompleteTag(arg string) []string {
 func TestComplete(t *testing.T) {
 	vectors := []struct {
 		cmdline     string
-		completions []string
+		completions []opt.Completion
 		prefix      string
 	}{
 		{
 			"foo --delay 33..33.3 -n",
-			[]string{"-n "},
+			[]opt.Completion{{Value: "-n "}},
 			"foo --delay 33..33.3 ",
 		},
 		{
 			"foo --delay 33..33.3 -n ",
-			[]string{"leonardo", "michelangelo", "rafaelo", "donatello"},
+			[]opt.Completion{
+				{Value: "leonardo"},
+				{Value: "michelangelo"},
+				{Value: "rafaelo"},
+				{Value: "donatello"},
+			},
 			"foo --delay 33..33.3 -n ",
 		},
 		{
 			"foo --delay 33..33.3 -n don",
-			[]string{"donatello"},
+			[]opt.Completion{{Value: "donatello"}},
 			"foo --delay 33..33.3 -n ",
 		},
 		{
 			"foo --delay 33..33.3 --name=",
-			[]string{"leonardo", "michelangelo", "rafaelo", "donatello"},
+			[]opt.Completion{
+				{Value: "leonardo"},
+				{Value: "michelangelo"},
+				{Value: "rafaelo"},
+				{Value: "donatello"},
+			},
 			"foo --delay 33..33.3 --name=",
 		},
 		{
 			"foo --delay 33..33.3 --name=leo",
-			[]string{"leonardo"},
+			[]opt.Completion{{Value: "leonardo"}},
 			"foo --delay 33..33.3 --name=",
 		},
 		{
 			"foo --nam",
-			[]string{
-				"--name ",
-			},
+			[]opt.Completion{{Value: "--name "}},
 			"foo ",
 		},
 		{
 			"foo --delay 33..33.3 --backoff",
-			[]string{
-				"--backoff ",
-			},
+			[]opt.Completion{{Value: "--backoff ", Description: "Increase delay on error"}},
 			"foo --delay 33..33.3 ",
 		},
 		{
 			"foo --delay 33..33.3 -",
-			[]string{
-				"-unread",
-				"-sent",
-				"-important",
-				"-inbox",
-				"-trash",
-				"-n ",
-				"--name ",
-				"-z ",
-				"-B ",
-				"--backoff ",
+			[]opt.Completion{
+				{Value: "-unread"},
+				{Value: "-sent"},
+				{Value: "-important"},
+				{Value: "-inbox"},
+				{Value: "-trash"},
+				{Value: "-n "},
+				{Value: "--name "},
+				{Value: "-z ", Description: "Print zero values"},
+				{Value: "-B ", Description: "Increase delay on error"},
+				{Value: "--backoff ", Description: "Increase delay on error"},
 			},
 			"foo --delay 33..33.3 ",
 		},
 		{
 			"foo --delay 33..33.3 ",
-			[]string{
-				"unread",
-				"sent",
-				"important",
-				"inbox",
-				"trash",
-				"-n ",
-				"--name ",
-				"-z ",
-				"-B ",
-				"--backoff ",
+			[]opt.Completion{
+				{Value: "unread"},
+				{Value: "sent"},
+				{Value: "important"},
+				{Value: "inbox"},
+				{Value: "trash"},
+				{Value: "-n "},
+				{Value: "--name "},
+				{Value: "-z ", Description: "Print zero values"},
+				{Value: "-B ", Description: "Increase delay on error"},
+				{Value: "--backoff ", Description: "Increase delay on error"},
 			},
 			"foo --delay 33..33.3 ",
 		},
 		{
 			"foo --delay 33..33.3 -n leonardo i",
-			[]string{"important", "inbox"},
+			[]opt.Completion{{Value: "important"}, {Value: "inbox"}},
 			"foo --delay 33..33.3 -n leonardo ",
 		},
 		{
 			"foo +",
-			[]string{"+unread", "+sent", "+important", "+inbox", "+trash"},
+			[]opt.Completion{
+				{Value: "+unread"},
+				{Value: "+sent"},
+				{Value: "+important"},
+				{Value: "+inbox"},
+				{Value: "+trash"},
+			},
 			"foo ",
 		},
 		{
 			"foo -i",
-			[]string{"-important", "-inbox"},
+			[]opt.Completion{{Value: "-important"}, {Value: "-inbox"}},
 			"foo ",
 		},
 	}

@@ 83,6 83,10 @@ be a method with a pointer receiver to the struct itself, takes a single
 `string` argument and may return an `error` to abort parsing. The `action`
 method is responsible of updating the struct.
 
+### `description:"foobaz"` or `desc:"foobaz"`
+
+A description that is returned alongside arguments during autocompletion.
+
 ### `default:"foobaz"`
 
 Default `string` value if not specified by the user. Will be processed by the


@@ 148,7 152,7 @@ func ArgsToStruct(args *Args, v any) error {
 	return nil
 }
 
-func GetCompletions(cmdline string, v any) (completions []string, prefix string) {
+func GetCompletions(cmdline string, v any) (completions []Completion, prefix string) {
 	args := LexArgs(cmdline)
 	if args.Count() == 0 {
 		return nil, ""

@@ 56,6 56,8 @@ type optSpec struct {
 	kind optKind
 	// argument is required
 	required bool
+	// option/argument description
+	description string
 	// argument was seen on the command line
 	seen bool
 	// argument value was seen on the command line (only applies to options)


@@ 218,6 220,11 @@ func (spec *optSpec) parseField(struc reflect.Value, t reflect.StructField) {
 		spec.metavar = metavar
 	}
 
+	spec.description = t.Tag.Get("description")
+	if spec.description == "" {
+		spec.description = t.Tag.Get("desc")
+	}
+
 	spec.defval = t.Tag.Get("default")
 
 	switch t.Tag.Get("required") {