docs: update config descriptions to align with user intent

Author: tmihoc

cmd/juju/action/exec.go

@@ -162,15 +162,15 @@ func (c *execCommand) SetFlags(f *gnuflag.FlagSet) {
 		"plain": c.printExecOutput,
 	})
 
-	f.BoolVar(&c.all, "all", false, "Run the commands on all the machines")
-	f.BoolVar(&c.operator, "operator", false, "Run the commands on the operator (k8s-only)")
-	f.BoolVar(&c.parallel, "parallel", true, "Run the commands in parallel without first acquiring a lock")
-	f.StringVar(&c.executionGroup, "execution-group", "", "Commands in the same execution group are run sequentially")
-	f.Var(cmd.NewStringsValue(nil, &c.machines), "machine", "One or more machine ids")
-	f.Var(cmd.NewStringsValue(nil, &c.applications), "a", "One or more application names")
+	f.BoolVar(&c.all, "all", false, "Run the commands on all the machines.")
+	f.BoolVar(&c.operator, "operator", false, "Run the commands on the operator (Kubernetes only).")
+	f.BoolVar(&c.parallel, "parallel", true, "Run the commands in parallel without first acquiring a lock.")
+	f.StringVar(&c.executionGroup, "execution-group", "", "Specify an execution group; commands in the same group are run sequentially.")
+	f.Var(cmd.NewStringsValue(nil, &c.machines), "machine", "Specify one or more machine IDs.")
+	f.Var(cmd.NewStringsValue(nil, &c.applications), "a", "Specify one or more application names.")
 	f.Var(cmd.NewStringsValue(nil, &c.applications), "app", "")
 	f.Var(cmd.NewStringsValue(nil, &c.applications), "application", "")
-	f.Var(cmd.NewStringsValue(nil, &c.units), "u", "One or more unit ids")
+	f.Var(cmd.NewStringsValue(nil, &c.units), "u", "Specify one or more unit IDs.")
 	f.Var(cmd.NewStringsValue(nil, &c.units), "unit", "")
 }
 

cmd/juju/action/list.go

@@ -64,7 +64,7 @@ func (c *listCommand) SetFlags(f *gnuflag.FlagSet) {
 		"tabular": c.printTabular,
 		"default": c.dummyDefault,
 	})
-	f.BoolVar(&c.fullSchema, "schema", false, "Display the full action schema")
+	f.BoolVar(&c.fullSchema, "schema", false, "Display the full action schema.")
 }
 
 func (c *listCommand) Info() *cmd.Info {

cmd/juju/action/listoperations.go

@@ -79,21 +79,21 @@ func (c *listOperationsCommand) SetFlags(f *gnuflag.FlagSet) {
 		"plain": c.formatTabular,
 	})
 
-	f.BoolVar(&c.utc, "utc", false, "Show times in UTC")
-	f.Var(cmd.NewStringsValue(nil, &c.applicationNames), "applications", "Comma separated list of applications to filter on")
-	f.Var(cmd.NewStringsValue(nil, &c.applicationNames), "apps", "Comma separated list of applications to filter on")
-	f.Var(cmd.NewStringsValue(nil, &c.unitNames), "units", "Comma separated list of units to filter on")
-	f.Var(cmd.NewStringsValue(nil, &c.machineNames), "machines", "Comma separated list of machines to filter on")
-	f.Var(cmd.NewStringsValue(nil, &c.actionNames), "actions", "Comma separated list of actions names to filter on")
-	f.Var(cmd.NewStringsValue(nil, &c.statusValues), "status", "Comma separated list of operation status values to filter on")
-	f.UintVar(&c.limit, "limit", 0, "The maximum number of operations to return")
-	f.UintVar(&c.offset, "offset", 0, "Return operations from offset onwards")
+	f.BoolVar(&c.utc, "utc", false, "Show times in UTC.")
+	f.Var(cmd.NewStringsValue(nil, &c.applicationNames), "applications", "Specify a comma-separated list of applications to filter on.")
+	f.Var(cmd.NewStringsValue(nil, &c.applicationNames), "apps", "Specify a comma-separated list of applications to filter on.")
+	f.Var(cmd.NewStringsValue(nil, &c.unitNames), "units", "Specify a comma-separated list of units to filter on.")
+	f.Var(cmd.NewStringsValue(nil, &c.machineNames), "machines", "Specify a comma-separated list of machines to filter on.")
+	f.Var(cmd.NewStringsValue(nil, &c.actionNames), "actions", "Specify a comma-separated list of actions names to filter on.")
+	f.Var(cmd.NewStringsValue(nil, &c.statusValues), "status", "Specify a comma-separated list of operation status values to filter on.")
+	f.UintVar(&c.limit, "limit", 0, "Specify the maximum number of operations to return.")
+	f.UintVar(&c.offset, "offset", 0, "Specify the offset to start returning operations from.")
 }
 
 func (c *listOperationsCommand) Info() *cmd.Info {
 	return jujucmd.Info(&cmd.Info{
 		Name:     "operations",
-		Purpose:  "Lists pending, running, or completed operations for specified application, units, machines, or all.",
+		Purpose:  "List pending, running, or completed operations for specified application, units, machines, or all.",
 		Doc:      listOperationsDoc,
 		Aliases:  []string{"list-operations"},
 		Examples: listOperationsExamples,

cmd/juju/action/run.go

@@ -103,8 +103,8 @@ const runExamples = `
 func (c *runCommand) SetFlags(f *gnuflag.FlagSet) {
 	c.runCommandBase.SetFlags(f)
 
-	f.Var(&c.paramsYAML, "params", "Path to yaml-formatted params file")
-	f.BoolVar(&c.parseStrings, "string-args", false, "Use raw string values of CLI args")
+	f.Var(&c.paramsYAML, "params", "Specify the path to a yaml-formatted params file.")
+	f.BoolVar(&c.parseStrings, "string-args", false, "Use raw string values of CLI args.")
 }
 
 func (c *runCommand) Info() *cmd.Info {

cmd/juju/action/show.go

@@ -58,7 +58,7 @@ func (c *showCommand) Info() *cmd.Info {
 	info := jujucmd.Info(&cmd.Info{
 		Name:     "show-action",
 		Args:     "<application> <action>",
-		Purpose:  "Shows detailed information about an action.",
+		Purpose:  "Show detailed information about an action.",
 		Doc:      showActionDoc,
 		Examples: showActionExamples,
 		SeeAlso: []string{

cmd/juju/action/showoperation.go

@@ -63,9 +63,9 @@ func (c *showOperationCommand) SetFlags(f *gnuflag.FlagSet) {
 		"json": cmd.FormatJson,
 	})
 
-	f.DurationVar(&c.wait, "wait", defaultOperationWait, "Wait for results")
-	f.BoolVar(&c.watch, "watch", false, "Wait indefinitely for results")
-	f.BoolVar(&c.utc, "utc", false, "Show times in UTC")
+	f.DurationVar(&c.wait, "wait", defaultOperationWait, "Specify the maximum wait time for results.")
+	f.BoolVar(&c.watch, "watch", false, "Wait indefinitely for results.")
+	f.BoolVar(&c.utc, "utc", false, "Show times in UTC.")
 }
 
 // Info implements Command.

cmd/juju/action/showtask.go

@@ -75,9 +75,9 @@ func (c *showTaskCommand) SetFlags(f *gnuflag.FlagSet) {
 		"plain": printOutput,
 	})
 
-	f.DurationVar(&c.wait, "wait", defaultTaskWait, "Maximum wait time for a task to complete")
-	f.BoolVar(&c.watch, "watch", false, "Wait indefinitely for results")
-	f.BoolVar(&c.utc, "utc", false, "Show times in UTC")
+	f.DurationVar(&c.wait, "wait", defaultTaskWait, "Specify the maximum wait time for a task to complete.")
+	f.BoolVar(&c.watch, "watch", false, "Wait indefinitely for results.")
+	f.BoolVar(&c.utc, "utc", false, "Show times in UTC.")
 }
 
 func (c *showTaskCommand) Info() *cmd.Info {

cmd/juju/agree/agree/agree.go

@@ -75,7 +75,7 @@ type agreeCommand struct {
 // SetFlags implements Command.SetFlags.
 func (c *agreeCommand) SetFlags(f *gnuflag.FlagSet) {
 	c.CommandBase.SetFlags(f)
-	f.BoolVar(&c.SkipTermContent, "yes", false, "Agree to terms non interactively")
+	f.BoolVar(&c.SkipTermContent, "yes", false, "Agree to terms non-interactively.")
 }
 
 // Info implements Command.Info.

cmd/juju/agree/listagreements/listagreements.go

@@ -34,11 +34,11 @@ type TermsServiceClient interface {
 }
 
 const listAgreementsDoc = `
+List the terms that the user has agreed to.
+
 Charms may require a user to accept its terms in order for it to be deployed.
 In other words, some applications may only be installed if a user agrees to 
 accept some terms defined by the charm. 
-
-This command lists the terms that the user has agreed to.
 `
 
 const listAgreementsExamples = `

cmd/juju/application/addunit.go

@@ -23,11 +23,10 @@ import (
 	"github.com/juju/juju/rpc/params"
 )
 
-var usageAddUnitSummary = `Adds one or more units to a deployed application.`
+var usageAddUnitSummary = `Add one or more units to a deployed application.`
 
 var usageAddUnitDetails = `
-The ` + "`add-unit`" + ` command is used to scale out an application for improved performance or
-availability.
+Scale out an application for improved performance or availability.
 
 Note: Some charms will seamlessly support horizontal scaling while others may need
 an additional application support (e.g. a separate load balancer). See the
@@ -94,7 +93,7 @@ type UnitCommandBase struct {
 }
 
 func (c *UnitCommandBase) SetFlags(f *gnuflag.FlagSet) {
-	f.IntVar(&c.NumUnits, "num-units", 1, "")
+	f.IntVar(&c.NumUnits, "num-units", 1, "Set the number of units to add.")
 	f.StringVar(&c.PlacementSpec, "to", "", "(Machine models only) Specify a comma-separated list of placement directives. If the length of this list is less than `-n`, the remaining units will be added in the default way (i.e., to new machines).")
 	f.Var(attachStorageFlag{&c.AttachStorage}, "attach-storage", "Specify an existing storage volume to attach to the deployed unit.")
 }
@@ -158,7 +157,7 @@ func (c *addUnitCommand) Info() *cmd.Info {
 
 func (c *addUnitCommand) SetFlags(f *gnuflag.FlagSet) {
 	c.UnitCommandBase.SetFlags(f)
-	f.IntVar(&c.NumUnits, "n", 1, "Specify the number of units to add.")
+	f.IntVar(&c.NumUnits, "n", 1, "Set the number of units to add")
 }
 
 func (c *addUnitCommand) Init(args []string) error {