Merge pull request juju#17486 from ycliuhw/cmd-docstring-fix

juju#17486

This PR is fixing docstrings for juju commands, mainly for adding SeeAlso and Example docs.

cmd/juju/action/cancel.go

@@ -37,12 +37,26 @@ func (c *cancelCommand) SetFlags(f *gnuflag.FlagSet) {
 const cancelDoc = `
 Cancel pending or running tasks matching given IDs or partial ID prefixes.`
 
+const cancelExamples = `
+To cancel a task by ID:
+
+    juju cancel-task 1
+
+To cancel multiple tasks by ID:
+
+    juju cancel-task 1 2 3
+`
+
 func (c *cancelCommand) Info() *cmd.Info {
 	info := &cmd.Info{
-		Name:    "cancel-task",
-		Args:    "(<task-id>|<task-id-prefix>) [...]",
-		Purpose: "Cancel pending or running tasks.",
-		Doc:     cancelDoc,
+		Name:     "cancel-task",
+		Args:     "(<task-id>|<task-id-prefix>) [...]",
+		Purpose:  "Cancel pending or running tasks.",
+		Doc:      cancelDoc,
+		Examples: cancelExamples,
+		SeeAlso: []string{
+			"show-task",
+		},
 	}
 	return jujucmd.Info(info)
 }

cmd/juju/action/exec.go

@@ -123,13 +123,27 @@ those arguments. For example:
 
 `
 
+const example = `
+
+    juju exec --all -- hostname -f
+
+    juju exec --unit hello/0 env
+
+    juju exec --unit controller/0 juju-engine-report
+`
+
 // Info implements Command.Info.
 func (c *execCommand) Info() *cmd.Info {
 	info := jujucmd.Info(&cmd.Info{
-		Name:    "exec",
-		Args:    "<commands>",
-		Purpose: "Run the commands on the remote targets specified.",
-		Doc:     execDoc,
+		Name:     "exec",
+		Args:     "<commands>",
+		Purpose:  "Run the commands on the remote targets specified.",
+		Doc:      execDoc,
+		Examples: example,
+		SeeAlso: []string{
+			"run",
+			"ssh",
+		},
 	})
 	return info
 }

cmd/juju/action/showtask.go

@@ -88,6 +88,7 @@ func (c *showTaskCommand) Info() *cmd.Info {
 		Doc:      showTaskDoc,
 		Examples: showTaskExamples,
 		SeeAlso: []string{
+			"cancel-task",
 			"run",
 			"operations",
 			"show-operation",

cmd/juju/agree/agree/agree.go

@@ -86,6 +86,9 @@ func (c *agreeCommand) Info() *cmd.Info {
 		Purpose:  "Agree to terms.",
 		Doc:      agreeDoc,
 		Examples: agreeExamples,
+		SeeAlso: []string{
+			"agreements",
+		},
 	})
 }
 

cmd/juju/agree/listagreements/listagreements.go

@@ -39,10 +39,10 @@ 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.
+`
 
-See also:
-    agree
-
+const listAgreementsExamples = `
+    juju agreements
 `
 
 // NewListAgreementsCommand returns a new command that can be
@@ -73,10 +73,14 @@ func (c *listAgreementsCommand) SetFlags(f *gnuflag.FlagSet) {
 // Info implements Command.Info.
 func (c *listAgreementsCommand) Info() *cmd.Info {
 	return jujucmd.Info(&cmd.Info{
-		Name:    "agreements",
-		Purpose: "List user's agreements.",
-		Doc:     listAgreementsDoc,
-		Aliases: []string{"list-agreements"},
+		Name:     "agreements",
+		Purpose:  "List user's agreements.",
+		Doc:      listAgreementsDoc,
+		Aliases:  []string{"list-agreements"},
+		Examples: listAgreementsExamples,
+		SeeAlso: []string{
+			"agree",
+		},
 	})
 }
 

cmd/juju/application/bind.go

@@ -84,6 +84,11 @@ func (c *bindCommand) Info() *cmd.Info {
 		Purpose:  "Change bindings for a deployed application.",
 		Doc:      bindCmdDoc,
 		Examples: bindCmdExamples,
+		SeeAlso: []string{
+			"spaces",
+			"show-space",
+			"show-application",
+		},
 	})
 }
 

cmd/juju/application/config.go

@@ -115,6 +115,24 @@ settings back to their default value as defined in the charm metadata:
     juju config apache2 --reset servername
     juju config apache2 --reset servername,lb_balancer_timeout
 `
+
+	examples = `
+To view all configuration values for an application, run
+
+    juju config mysql --format json
+
+To set a configuration value for an application, run
+
+    juju config mysql foo=bar
+
+To set some keys and reset others:
+
+    juju config mysql key1=val1 key2=val2 --reset key3,key4
+
+To set a configuration value for an application from a file:
+
+    juju config mysql --file=path/to/cfg.yaml
+`
 )
 
 var appConfigBase = config.ConfigCommandBase{
@@ -150,10 +168,11 @@ type ApplicationAPI interface {
 // Info is part of the cmd.Command interface.
 func (c *configCommand) Info() *cmd.Info {
 	return jujucmd.Info(&cmd.Info{
-		Name:    "config",
-		Args:    "<application name> [--branch <branch-name>] [--reset <key[,key]>] [<attribute-key>][=<value>] ...]",
-		Purpose: configSummary,
-		Doc:     configDetails,
+		Name:     "config",
+		Args:     "<application name> [--branch <branch-name>] [--reset <key[,key]>] [<attribute-key>][=<value>] ...]",
+		Purpose:  configSummary,
+		Doc:      configDetails,
+		Examples: examples,
 		SeeAlso: []string{
 			"deploy",
 			"status",

cmd/juju/application/expose.go

@@ -66,6 +66,24 @@ juju expose apache2 --endpoints logs --to-cidrs 192.168.0.0/24
 
 `[1:]
 
+const example = `
+To expose an application:
+
+    juju expose apache2
+
+To expose an application to one or multiple spaces:
+
+    juju expose apache2 --to-spaces public
+
+To expose an application to one or multiple endpoints:
+
+    juju expose apache2 --endpoints logs
+	
+To expose an application to one or multiple CIDRs:
+
+    juju expose apache2 --to-cidrs 10.0.0.0/24
+`
+
 // NewExposeCommand returns a command to expose applications.
 func NewExposeCommand() modelcmd.ModelCommand {
 	return modelcmd.Wrap(&exposeCommand{})
@@ -82,10 +100,11 @@ type exposeCommand struct {
 
 func (c *exposeCommand) Info() *cmd.Info {
 	return jujucmd.Info(&cmd.Info{
-		Name:    "expose",
-		Args:    "<application name>",
-		Purpose: usageExposeSummary,
-		Doc:     usageExposeDetails,
+		Name:     "expose",
+		Args:     "<application name>",
+		Purpose:  usageExposeSummary,
+		Doc:      usageExposeDetails,
+		Examples: example,
 		SeeAlso: []string{
 			"unexpose",
 		},

cmd/juju/application/refresh.go

@@ -237,6 +237,20 @@ application; overriding profiles on the container may cause unexpected
 behavior.
 `
 
+const refreshExamples = `
+To refresh the storage constraints for the application foo:
+
+	juju refresh foo --storage cache=ssd,10G
+
+To refresh the application config from a file for application foo:
+
+	juju refresh foo --config config.yaml
+
+To refresh the resources for application foo:
+
+	juju refresh foo --resource bar=/some/file.tgz --resource baz=./docs/cfg.xml
+`
+
 const upgradedApplicationHasUnitsMessage = `
 Upgrading from an older PodSpec style charm to a newer Sidecar charm requires that
 the application be scaled down to 0 units.
@@ -249,10 +263,12 @@ all those units to disappear before continuing.
 
 func (c *refreshCommand) Info() *cmd.Info {
 	return jujucmd.Info(&cmd.Info{
-		Name:    "refresh",
-		Args:    "<application>",
-		Purpose: "Refresh an application's charm.",
-		Doc:     refreshDoc,
+		Name:     "refresh",
+		Args:     "<application>",
+		Purpose:  "Refresh an application's charm.",
+		Doc:      refreshDoc,
+		SeeAlso:  []string{"deploy"},
+		Examples: refreshExamples,
 	})
 }
 

cmd/juju/application/removeapplication.go

@@ -93,6 +93,10 @@ func (c *removeApplicationCommand) Info() *cmd.Info {
 		Purpose:  helpSummaryRmApp,
 		Doc:      helpDetailsRmApp,
 		Examples: helpExamplesRmApp,
+		SeeAlso: []string{
+			"scale-application",
+			"show-application",
+		},
 	})
 }
 

cmd/juju/application/resolved.go

@@ -29,12 +29,22 @@ type resolvedCommand struct {
 	All       bool
 }
 
+const resolvedCommandExamples = `
+
+	juju resolved mysql/0
+
+	juju resolved mysql/0 mysql/1
+
+	juju resolved --all
+`
+
 func (c *resolvedCommand) Info() *cmd.Info {
 	return jujucmd.Info(&cmd.Info{
-		Name:    "resolved",
-		Args:    "[<unit> ...]",
-		Purpose: "Marks unit errors resolved and re-executes failed hooks.",
-		Aliases: []string{"resolve"},
+		Name:     "resolved",
+		Args:     "[<unit> ...]",
+		Purpose:  "Marks unit errors resolved and re-executes failed hooks.",
+		Aliases:  []string{"resolve"},
+		Examples: resolvedCommandExamples,
 	})
 }
 

cmd/juju/application/scaleapplication.go

@@ -58,6 +58,11 @@ func (c *scaleApplicationCommand) Info() *cmd.Info {
 		Purpose:  "Set the desired number of k8s application units.",
 		Doc:      scaleApplicationDoc,
 		Examples: scaleApplicationExamples,
+		SeeAlso: []string{
+			"remove-application",
+			"add-unit",
+			"remove-unit",
+		},
 	})
 }
 

cmd/juju/application/showunit.go

@@ -25,10 +25,24 @@ or related unit may be shown, or just the application data.
 `
 
 const showUnitExamples = `
+To show information about a unit:
+
     juju show-unit mysql/0
+
+To show information about multiple units:
+
     juju show-unit mysql/0 wordpress/1
+
+To show only the application relation data for a unit:
+
     juju show-unit mysql/0 --app
+
+To show only the relation data for a specific endpoint:
+
     juju show-unit mysql/0 --endpoint db
+
+To show only the relation data for a specific related unit:
+
     juju show-unit mysql/0 --related-unit wordpress/2
 `
 
@@ -61,6 +75,10 @@ func (c *showUnitCommand) Info() *cmd.Info {
 		Purpose:  "Displays information about a unit.",
 		Doc:      showUnitDoc,
 		Examples: showUnitExamples,
+		SeeAlso: []string{
+			"add-unit",
+			"remove-unit",
+		},
 	}
 	return jujucmd.Info(showCmd)
 }

cmd/juju/application/unexpose.go

@@ -26,24 +26,15 @@ the "juju expose" command, they can be unexposed by running the "juju unexpose"
 command.  
 
 If no additional options are specified, the command will unexpose the
-application (if exposed). For example, to unexpose the apache2 application,
-you can run:
-
-juju unexpose apache2
+application (if exposed).
 
 The --endpoints option may be used to restrict the effect of this command to 
-the list of ports opened for a comma-delimited list of endpoints. For instance,
-to only unexpose the ports opened by apache2 for the "www" endpoint, you can 
-run:
-
-juju unexpose apache2 --endpoints www
+the list of ports opened for a comma-delimited list of endpoints.
 
 Note that when the --endpoints option is provided, the application will still
 remain exposed if any other of its endpoints are still exposed. However, if
 none of its endpoints remain exposed, the application will be instead unexposed. 
-
-See also: 
-    expose`[1:]
+`[1:]
 
 // NewUnexposeCommand returns a command to unexpose applications.
 func NewUnexposeCommand() modelcmd.ModelCommand {
@@ -57,12 +48,26 @@ type unexposeCommand struct {
 	ExposedEndpointsList string
 }
 
+const unexposeCommandExample = `
+    juju unexpose apache2
+
+To unexpose only the ports that charms have opened for the "www", or "www" and "logs" endpoints:
+
+    juju unexpose apache2 --endpoints www
+
+    juju unexpose apache2 --endpoints www,logs
+`
+
 func (c *unexposeCommand) Info() *cmd.Info {
 	return jujucmd.Info(&cmd.Info{
-		Name:    "unexpose",
-		Args:    "<application name>",
-		Purpose: usageUnexposeSummary,
-		Doc:     usageUnexposeDetails,
+		Name:     "unexpose",
+		Args:     "<application name>",
+		Purpose:  usageUnexposeSummary,
+		Doc:      usageUnexposeDetails,
+		Examples: unexposeCommandExample,
+		SeeAlso: []string{
+			"expose",
+		},
 	})
 }