diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 71a9bda5..93267bbf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,6 +35,16 @@ goreleaser --snapshot --skip-publish --rm-dist ## Conventions +### Command usage + +Command usage descriptions (namely `cobra.Command.Use`) should follow the [docopt](http://docopt.org/) syntax. + +Additionally: +- Optional flags should be the first in the usage string. + - If there is more than one optional flag, you can use `[options]` to abbreviate. +- Required flags should always be documented explicitly and before the positional arguments, but after the + optional flags. + ### Subcommand groups Cobra offers the functionality to group subcommands. The conventions on when and how to group commands are as follows: diff --git a/internal/cmd/all/list.go b/internal/cmd/all/list.go index 37a9ac12..efa56950 100644 --- a/internal/cmd/all/list.go +++ b/internal/cmd/all/list.go @@ -50,7 +50,7 @@ var ListCmd = base.Cmd{ } cmd := &cobra.Command{ - Use: "list FLAGS", + Use: "list [options]", Short: "List all resources in the project", Long: `List all resources in the project. This does not include static/public resources like locations, public ISOs, etc. diff --git a/internal/cmd/base/delete.go b/internal/cmd/base/delete.go index a1ef8342..1f215805 100644 --- a/internal/cmd/base/delete.go +++ b/internal/cmd/base/delete.go @@ -26,8 +26,13 @@ type DeleteCmd struct { // CobraCommand creates a command that can be registered with cobra. func (dc *DeleteCmd) CobraCommand(s state.State) *cobra.Command { + opts := "" + if dc.AdditionalFlags != nil { + opts = "[options] " + } + cmd := &cobra.Command{ - Use: fmt.Sprintf("delete [FLAGS] %s", strings.ToUpper(dc.ResourceNameSingular)), + Use: fmt.Sprintf("delete %s<%s>", opts, strings.ToLower(dc.ResourceNameSingular)), Short: dc.ShortDescription, Args: cobra.ExactArgs(1), ValidArgsFunction: cmpl.SuggestArgs(cmpl.SuggestCandidatesF(dc.NameSuggestions(s.Client()))), diff --git a/internal/cmd/base/describe.go b/internal/cmd/base/describe.go index 2edb556d..0e3b7bcd 100644 --- a/internal/cmd/base/describe.go +++ b/internal/cmd/base/describe.go @@ -33,7 +33,7 @@ type DescribeCmd struct { // CobraCommand creates a command that can be registered with cobra. func (dc *DescribeCmd) CobraCommand(s state.State) *cobra.Command { cmd := &cobra.Command{ - Use: fmt.Sprintf("describe [FLAGS] %s", strings.ToUpper(dc.ResourceNameSingular)), + Use: fmt.Sprintf("describe [options] <%s>", strings.ToLower(dc.ResourceNameSingular)), Short: dc.ShortDescription, Args: cobra.ExactArgs(1), ValidArgsFunction: cmpl.SuggestArgs(cmpl.SuggestCandidatesF(dc.NameSuggestions(s.Client()))), diff --git a/internal/cmd/base/labels.go b/internal/cmd/base/labels.go index 71897c0a..a3aa4dbd 100644 --- a/internal/cmd/base/labels.go +++ b/internal/cmd/base/labels.go @@ -27,7 +27,7 @@ type LabelCmds struct { // AddCobraCommand creates a command that can be registered with cobra. func (lc *LabelCmds) AddCobraCommand(s state.State) *cobra.Command { cmd := &cobra.Command{ - Use: fmt.Sprintf("add-label [FLAGS] %s LABEL...", strings.ToUpper(lc.ResourceNameSingular)), + Use: fmt.Sprintf("add-label [--overwrite] <%s>