completion: add command option descriptions

Add `desc:""` struct field tags in all command arguments where it makes sense. The description values will be returned along with completion choices. Implements: https://todo.sr.ht/~rjarry/aerc/271 Signed-off-by: Robin Jarry <[email protected]> Tested-by: Bojan Gabric <[email protected]> Tested-by: Jason Cox <[email protected]> Acked-by: Tim Culverhouse <[email protected]>
rjarry · Oct 23, 2024 · d0484b1 · d0484b1
1 parent 26033ea
commit d0484b1
Show file tree

Hide file tree

Showing 58 changed files with 155 additions and 166 deletions.
diff --git a/commands/account/align.go b/commands/account/align.go
@@ -9,7 +9,7 @@ import (
 )
 
 type Align struct {
-	Pos app.AlignPosition `opt:"pos" metavar:"top|center|bottom" action:"ParsePos" complete:"CompletePos"`
+	Pos app.AlignPosition `opt:"pos" metavar:"top|center|bottom" action:"ParsePos" complete:"CompletePos" desc:"Position."`
 }
 
 func init() {

diff --git a/commands/account/cf.go b/commands/account/cf.go
@@ -14,8 +14,8 @@ import (
 )
 
 type ChangeFolder struct {
-	Account bool   `opt:"-a"`
-	Folder  string `opt:"..." complete:"CompleteFolderAndNotmuch"`
+	Account string `opt:"-a" complete:"CompleteAccount" desc:"Change to specified account."`
+	Folder  string `opt:"..." complete:"CompleteFolderAndNotmuch" desc:"Folder name."`
 }
 
 func init() {
@@ -34,20 +34,12 @@ func (ChangeFolder) Aliases() []string {
 	return []string{"cf"}
 }
 
-func (c *ChangeFolder) CompleteFolderAndNotmuch(arg string) []string {
-	var acct *app.AccountView
+func (c *ChangeFolder) CompleteAccount(arg string) []string {
+	return commands.FilterList(app.AccountNames(), arg, commands.QuoteSpace)
+}
 
-	args := opt.LexArgs(c.Folder)
-	if c.Account {
-		accountName, _ := args.ArgSafe(0)
-		if args.Count() <= 1 && arg == accountName {
-			return commands.FilterList(
-				app.AccountNames(), arg, commands.QuoteSpace)
-		}
-		acct, _ = app.Account(accountName)
-	} else {
-		acct = app.SelectedAccount()
-	}
+func (c *ChangeFolder) CompleteFolderAndNotmuch(arg string) []string {
+	acct := app.SelectedAccount()
 	if acct == nil {
 		return nil
 	}
@@ -77,15 +69,12 @@ func (c *ChangeFolder) CompleteFolderAndNotmuch(arg string) []string {
 func (c ChangeFolder) Execute([]string) error {
 	var target string
 	var acct *app.AccountView
+	var err error
 
 	args := opt.LexArgs(c.Folder)
 
-	if c.Account {
-		names, err := args.ShiftSafe(1)
-		if err != nil {
-			return errors.New("<account> is required. Usage: cf -a <account> <folder>")
-		}
-		acct, err = app.Account(names[0])
+	if c.Account != "" {
+		acct, err = app.Account(c.Account)
 		if err != nil {
 			return err
 		}

diff --git a/commands/account/clear.go b/commands/account/clear.go
@@ -9,7 +9,7 @@ import (
 )
 
 type Clear struct {
-	Selected bool `opt:"-s"`
+	Selected bool `opt:"-s" desc:"Select first message after clearing."`
 }
 
 func init() {

diff --git a/commands/account/compose.go b/commands/account/compose.go
@@ -16,10 +16,10 @@ import (
 )
 
 type Compose struct {
-	Headers  string `opt:"-H" action:"ParseHeader"`
-	Template string `opt:"-T" complete:"CompleteTemplate"`
-	Edit     bool   `opt:"-e"`
-	NoEdit   bool   `opt:"-E"`
+	Headers  string `opt:"-H" action:"ParseHeader" desc:"Add the specified header to the message."`
+	Template string `opt:"-T" complete:"CompleteTemplate" desc:"Template name."`
+	Edit     bool   `opt:"-e" desc:"Force [compose].edit-headers = true."`
+	NoEdit   bool   `opt:"-E" desc:"Force [compose].edit-headers = false."`
 	Body     string `opt:"..." required:"false"`
 }
 

diff --git a/commands/account/export-mbox.go b/commands/account/export-mbox.go
@@ -19,7 +19,7 @@ import (
 )
 
 type ExportMbox struct {
-	Filename string `opt:"filename" complete:"CompleteFilename"`
+	Filename string `opt:"filename" complete:"CompleteFilename" desc:"Output file path."`
 }
 
 func init() {

diff --git a/commands/account/import-mbox.go b/commands/account/import-mbox.go
@@ -19,7 +19,7 @@ import (
 )
 
 type ImportMbox struct {
-	Filename string `opt:"filename" complete:"CompleteFilename"`
+	Filename string `opt:"filename" complete:"CompleteFilename" desc:"Input file path."`
 }
 
 func init() {

diff --git a/commands/account/mkdir.go b/commands/account/mkdir.go
@@ -11,7 +11,7 @@ import (
 )
 
 type MakeDir struct {
-	Folder string `opt:"folder" complete:"CompleteFolder"`
+	Folder string `opt:"folder" complete:"CompleteFolder" desc:"Folder name."`
 }
 
 func init() {

diff --git a/commands/account/query.go b/commands/account/query.go
@@ -11,10 +11,10 @@ import (
 )
 
 type Query struct {
-	Account string `opt:"-a" complete:"CompleteAccount"`
-	Name    string `opt:"-n"`
-	Force   bool   `opt:"-f"`
-	Query   string `opt:"..." complete:"CompleteNotmuch"`
+	Account string `opt:"-a" complete:"CompleteAccount" desc:"Account name."`
+	Name    string `opt:"-n" desc:"Force name of virtual folder."`
+	Force   bool   `opt:"-f" desc:"Replace existing query if any."`
+	Query   string `opt:"..." complete:"CompleteNotmuch" desc:"Notmuch query."`
 }
 
 func init() {

diff --git a/commands/account/recover.go b/commands/account/recover.go
@@ -13,10 +13,10 @@ import (
 )
 
 type Recover struct {
-	Force  bool   `opt:"-f"`
-	Edit   bool   `opt:"-e"`
-	NoEdit bool   `opt:"-E"`
-	File   string `opt:"file" complete:"CompleteFile"`
+	Force  bool   `opt:"-f" desc:"Delete recovered file after opening the composer."`
+	Edit   bool   `opt:"-e" desc:"Force [compose].edit-headers = true."`
+	NoEdit bool   `opt:"-E" desc:"Force [compose].edit-headers = false."`
+	File   string `opt:"file" complete:"CompleteFile" desc:"Recover file path."`
 }
 
 func init() {

diff --git a/commands/account/rmdir.go b/commands/account/rmdir.go
@@ -13,8 +13,8 @@ import (
 )
 
 type RemoveDir struct {
-	Force  bool   `opt:"-f"`
-	Folder string `opt:"folder" complete:"CompleteFolder" required:"false"`
+	Force  bool   `opt:"-f" desc:"Remove the directory even if it contains messages."`
+	Folder string `opt:"folder" complete:"CompleteFolder" required:"false" desc:"Folder name."`
 }
 
 func init() {

diff --git a/commands/account/search.go b/commands/account/search.go
@@ -19,20 +19,20 @@ import (
 )
 
 type SearchFilter struct {
-	Read         bool                 `opt:"-r" action:"ParseRead"`
-	Unread       bool                 `opt:"-u" action:"ParseUnread"`
-	Body         bool                 `opt:"-b"`
-	All          bool                 `opt:"-a"`
-	UseExtension bool                 `opt:"-e"`
-	Headers      textproto.MIMEHeader `opt:"-H" action:"ParseHeader" metavar:"<header>:<value>"`
-	WithFlags    models.Flags         `opt:"-x" action:"ParseFlag" complete:"CompleteFlag"`
-	WithoutFlags models.Flags         `opt:"-X" action:"ParseNotFlag" complete:"CompleteFlag"`
-	To           []string             `opt:"-t" action:"ParseTo" complete:"CompleteAddress"`
-	From         []string             `opt:"-f" action:"ParseFrom" complete:"CompleteAddress"`
-	Cc           []string             `opt:"-c" action:"ParseCc" complete:"CompleteAddress"`
-	StartDate    time.Time            `opt:"-d" action:"ParseDate" complete:"CompleteDate"`
+	Read         bool                 `opt:"-r" action:"ParseRead" desc:"Search for read messages."`
+	Unread       bool                 `opt:"-u" action:"ParseUnread" desc:"Search for unread messages."`
+	Body         bool                 `opt:"-b" desc:"Search in the body of the messages."`
+	All          bool                 `opt:"-a" desc:"Search in the entire text of the messages."`
+	UseExtension bool                 `opt:"-e" desc:"Use custom search backend extension."`
+	Headers      textproto.MIMEHeader `opt:"-H" action:"ParseHeader" metavar:"<header>:<value>" desc:"Search for messages with the specified header."`
+	WithFlags    models.Flags         `opt:"-x" action:"ParseFlag" complete:"CompleteFlag" desc:"Search messages with specified flag."`
+	WithoutFlags models.Flags         `opt:"-X" action:"ParseNotFlag" complete:"CompleteFlag" desc:"Search messages without specified flag."`
+	To           []string             `opt:"-t" action:"ParseTo" complete:"CompleteAddress" desc:"Search for messages To:<address>."`
+	From         []string             `opt:"-f" action:"ParseFrom" complete:"CompleteAddress" desc:"Search for messages From:<address>."`
+	Cc           []string             `opt:"-c" action:"ParseCc" complete:"CompleteAddress" desc:"Search for messages Cc:<address>."`
+	StartDate    time.Time            `opt:"-d" action:"ParseDate" complete:"CompleteDate" desc:"Search for messages within a particular date range."`
 	EndDate      time.Time
-	Terms        string `opt:"..." required:"false" complete:"CompleteTerms"`
+	Terms        string `opt:"..." required:"false" complete:"CompleteTerms" desc:"Search term."`
 }
 
 func init() {

diff --git a/commands/account/sort.go b/commands/account/sort.go
@@ -13,8 +13,8 @@ import (
 type Sort struct {
 	Unused struct{} `opt:"-"`
 	// these fields are only used for completion
-	Reverse  bool     `opt:"-r"`
-	Criteria []string `opt:"criteria" complete:"CompleteCriteria"`
+	Reverse  bool     `opt:"-r" desc:"Sort in the reverse order."`
+	Criteria []string `opt:"criteria" complete:"CompleteCriteria" desc:"Sort criterion."`
 }
 
 func init() {

diff --git a/commands/account/view.go b/commands/account/view.go
@@ -13,8 +13,8 @@ import (
 )
 
 type ViewMessage struct {
-	Peek       bool `opt:"-p"`
-	Background bool `opt:"-b"`
+	Peek       bool `opt:"-p" desc:"Peek message without marking it as read."`
+	Background bool `opt:"-b" desc:"Open message in a background tab."`
 }
 
 func init() {

diff --git a/commands/cd.go b/commands/cd.go
@@ -11,7 +11,7 @@ import (
 var previousDir string
 
 type ChangeDirectory struct {
-	Target string `opt:"directory" default:"~" complete:"CompleteTarget"`
+	Target string `opt:"directory" default:"~" complete:"CompleteTarget" desc:"Target directory."`
 }
 
 func init() {

diff --git a/commands/compose/attach.go b/commands/compose/attach.go
@@ -21,9 +21,9 @@ import (
 )
 
 type Attach struct {
-	Menu bool   `opt:"-m"`
-	Name string `opt:"-r"`
-	Path string `opt:"path" required:"false" complete:"CompletePath"`
+	Menu bool   `opt:"-m" desc:"Select files from file-picker-cmd."`
+	Name string `opt:"-r" desc:"<name> <cmd...>: Generate attachment from command output."`
+	Path string `opt:"path" required:"false" complete:"CompletePath" desc:"Attachment file path."`
 	Args string `opt:"..." required:"false"`
 }
 

diff --git a/commands/compose/cc-bcc.go b/commands/compose/cc-bcc.go
@@ -6,7 +6,7 @@ import (
 )
 
 type CC struct {
-	Recipients string `opt:"recipients" complete:"CompleteAddress"`
+	Recipients string `opt:"recipients" complete:"CompleteAddress" desc:"Recipient from address book."`
 }
 
 func init() {

diff --git a/commands/compose/detach.go b/commands/compose/detach.go
@@ -11,7 +11,7 @@ import (
 )
 
 type Detach struct {
-	Path string `opt:"path" required:"false" complete:"CompletePath"`
+	Path string `opt:"path" required:"false" complete:"CompletePath" desc:"Attachment file path."`
 }
 
 func init() {

diff --git a/commands/compose/edit.go b/commands/compose/edit.go
@@ -9,8 +9,8 @@ import (
 )
 
 type Edit struct {
-	Edit   bool `opt:"-e"`
-	NoEdit bool `opt:"-E"`
+	Edit   bool `opt:"-e" desc:"Force [compose].edit-headers = true."`
+	NoEdit bool `opt:"-E" desc:"Force [compose].edit-headers = false."`
 }
 
 func init() {

diff --git a/commands/compose/header.go b/commands/compose/header.go
@@ -9,9 +9,9 @@ import (
 )
 
 type Header struct {
-	Force  bool   `opt:"-f"`
-	Remove bool   `opt:"-d"`
-	Name   string `opt:"name" complete:"CompleteHeaders"`
+	Force  bool   `opt:"-f" desc:"Overwrite any existing header."`
+	Remove bool   `opt:"-d" desc:"Remove the header instead of adding it."`
+	Name   string `opt:"name" complete:"CompleteHeaders" desc:"Header name."`
 	Value  string `opt:"..." required:"false"`
 }
 

diff --git a/commands/compose/multipart.go b/commands/compose/multipart.go
@@ -9,16 +9,16 @@ import (
 )
 
 type Multipart struct {
-	Remove bool   `opt:"-d"`
-	Mime   string `opt:"mime" metavar:"<mime/type>" complete:"CompleteMime"`
+	Remove bool   `opt:"-d" desc:"Remove the specified mime/type."`
+	Mime   string `opt:"mime" metavar:"<mime/type>" complete:"CompleteMime" desc:"MIME/type name."`
 }
 
 func init() {
 	commands.Register(Multipart{})
 }
 
 func (Multipart) Description() string {
-	return "Convert the message to multipart with the given mime-type part."
+	return "Convert the message to multipart with the given mime/type part."
 }
 
 func (Multipart) Context() commands.CommandContext {

diff --git a/commands/compose/postpone.go b/commands/compose/postpone.go
@@ -14,7 +14,7 @@ import (
 )
 
 type Postpone struct {
-	Folder string `opt:"-t" complete:"CompleteFolder"`
+	Folder string `opt:"-t" complete:"CompleteFolder" desc:"Override the target folder."`
 }
 
 func init() {

diff --git a/commands/compose/send.go b/commands/compose/send.go
@@ -24,11 +24,11 @@ import (
 )
 
 type Send struct {
-	Archive string `opt:"-a" action:"ParseArchive" metavar:"flat|year|month" complete:"CompleteArchive"`
-	CopyTo  string `opt:"-t" complete:"CompleteFolders"`
+	Archive string `opt:"-a" action:"ParseArchive" metavar:"flat|year|month" complete:"CompleteArchive" desc:"Archive the message being replied to."`
+	CopyTo  string `opt:"-t" complete:"CompleteFolders" desc:"Override the Copy-To folder."`
 
-	CopyToReplied   bool `opt:"-r"`
-	NoCopyToReplied bool `opt:"-R"`
+	CopyToReplied   bool `opt:"-r" desc:"Save sent message to current folder."`
+	NoCopyToReplied bool `opt:"-R" desc:"Do not save sent message to current folder."`
 }
 
 func init() {

diff --git a/commands/compose/switch.go b/commands/compose/switch.go
@@ -12,9 +12,9 @@ type AccountSwitcher interface {
 }
 
 type SwitchAccount struct {
-	Next    bool   `opt:"-n"`
-	Prev    bool   `opt:"-p"`
-	Account string `opt:"account" required:"false" complete:"CompleteAccount"`
+	Prev    bool   `opt:"-p" desc:"Switch to previous account."`
+	Next    bool   `opt:"-n" desc:"Switch to next account."`
+	Account string `opt:"account" required:"false" complete:"CompleteAccount" desc:"Account name."`
 }
 
 func init() {

diff --git a/commands/ct.go b/commands/ct.go
@@ -9,7 +9,7 @@ import (
 )
 
 type ChangeTab struct {
-	Tab string `opt:"tab" complete:"CompleteTab"`
+	Tab string `opt:"tab" complete:"CompleteTab" desc:"Tab name."`
 }
 
 func init() {

diff --git a/commands/eml.go b/commands/eml.go
@@ -12,7 +12,7 @@ import (
 )
 
 type Eml struct {
-	Path string `opt:"path" required:"false" complete:"CompletePath"`
+	Path string `opt:"path" required:"false" complete:"CompletePath" desc:"EML file path."`
 }
 
 func init() {

diff --git a/commands/help.go b/commands/help.go
@@ -7,7 +7,7 @@ import (
 )
 
 type Help struct {
-	Topic string `opt:"topic" action:"ParseTopic" default:"aerc" complete:"CompleteTopic"`
+	Topic string `opt:"topic" action:"ParseTopic" default:"aerc" complete:"CompleteTopic" desc:"Help topic."`
 }
 
 var pages = []string{

diff --git a/commands/menu.go b/commands/menu.go
@@ -16,12 +16,12 @@ import (
 )
 
 type Menu struct {
-	ErrExit     bool   `opt:"-e"`
-	Background  bool   `opt:"-b"`
-	Accounts    bool   `opt:"-a"`
-	Directories bool   `opt:"-d"`
-	Command     string `opt:"-c"`
-	Xargs       string `opt:"..." complete:"CompleteXargs"`
+	ErrExit     bool   `opt:"-e" desc:"Stop executing commands on the first error."`
+	Background  bool   `opt:"-b" desc:"Do NOT spawn the popover dialog."`
+	Accounts    bool   `opt:"-a" desc:"Feed command with account names."`
+	Directories bool   `opt:"-d" desc:"Feed command with folder names."`
+	Command     string `opt:"-c" desc:"Override [general].default-menu-cmd."`
+	Xargs       string `opt:"..." complete:"CompleteXargs" desc:"Command name."`
 }
 
 func init() {

diff --git a/commands/msg/archive.go b/commands/msg/archive.go
@@ -22,8 +22,8 @@ const (
 var ARCHIVE_TYPES = []string{ARCHIVE_FLAT, ARCHIVE_YEAR, ARCHIVE_MONTH}
 
 type Archive struct {
-	MultiFileStrategy *types.MultiFileStrategy `opt:"-m" action:"ParseMFS" complete:"CompleteMFS"`
-	Type              string                   `opt:"type" action:"ParseArchiveType" metavar:"flat|year|month" complete:"CompleteType"`
+	MultiFileStrategy *types.MultiFileStrategy `opt:"-m" action:"ParseMFS" complete:"CompleteMFS" desc:"Multi-file strategy."`
+	Type              string                   `opt:"type" action:"ParseArchiveType" metavar:"flat|year|month" complete:"CompleteType" desc:"Archiving scheme."`
 }
 
 func (a *Archive) ParseMFS(arg string) error {