Docs Audit: App Platform, Serverless Activations, etc... (#1413)

* Doc edits for:
* 1-click
* Accounts
* Compute Actions
* Serverless Activations
* App Platform

* syntax error in doc upgrade-buildpack doc string

* removed problematic syntax for now

* Updated syntax for existing examples to integrate better with Product documentation

* fixing script test

* multi example test

* minor clean up

* Fixed syntax errors in App Platform examples

* ran go fmt to fix errors

* Apply suggestions from code review

Suggestion from andrewsomething. Changes action IDs to integers instead of UUIDs.

Co-authored-by: Andrew Starr-Bochicchio <andrewsomething@users.noreply.github.com>

---------

Co-authored-by: Andrew Starr-Bochicchio <andrewsomething@users.noreply.github.com>

commands/1_clicks.go

@@ -34,6 +34,7 @@ func OneClicks() *Command {
 		aliasOpt("ls"), displayerType(&displayers.OneClick{}))
 
 	AddStringFlag(cmdOneClickList, doctl.ArgOneClickType, "", "", "The 1-Click type. Valid types are one of the following: kubernetes, droplet")
+	cmdOneClickList.Example = `The following example retrieves a list of 1-Click applications available for Droplets: doctl 1-click list --type droplet`
 
 	return cmd
 }

commands/account.go

@@ -34,23 +34,26 @@ For example, ` + "`" + `doctl account get` + "`" + ` retrieves account profile d
 		},
 	}
 
-	CmdBuilder(cmd, RunAccountGet, "get", "Retrieve account profile details", `Retrieve the following details from your account profile:
+	cmdAccountGet := CmdBuilder(cmd, RunAccountGet, "get", "Retrieve account profile details", `Retrieve the following details from your account profile:
 
 - Email address
+- Team 
 - Account Droplet limit
 - Email verification status
-- Account status (active or disabled)
-- UUID for the account.`, Writer,
+- UUID for the account
+- Account status (active or disabled).`, Writer,
 		aliasOpt("g"), displayerType(&displayers.Account{}))
+	cmdAccountGet.Example = `The following example retrieves email addresses associated with the account: doctl account get --format Email`
 
-	CmdBuilder(cmd, RunAccountRateLimit, "ratelimit", "Retrieve your API usage and the remaining quota", `Retrieve the following details about your account's API usage:
+	cmdAccountRateLimit := CmdBuilder(cmd, RunAccountRateLimit, "ratelimit", "Retrieve your API usage and the remaining quota", `Retrieve the following details about your account's API usage:
 
-- The current limit on your account for API calls (5,000 per hour per OAuth token)
+- The current limit on your account for API calls (default is 5,000 per hour per OAuth token)
 - The number of API calls you have made in the last hour
-- When the API call count is due to reset to zero, which happens hourly
+- When the API call count resets to zero, which happens hourly
 
-Note that these details are per OAuth token and are tied to the token you used when calling `+"`"+`doctl auth init`+"`"+` at setup time.`, Writer,
+Note that these details are per OAuth token and are bound to the token you used when calling `+"`"+`doctl auth init`+"`"+` at setup time.`, Writer,
 		aliasOpt("rl"), displayerType(&displayers.RateLimit{}))
+	cmdAccountRateLimit.Example = `The following example retrieves the number of API calls you have left for the hour: doctl account ratelimit --format Remaining`
 
 	return cmd
 }

commands/actions.go

@@ -32,37 +32,40 @@ func Actions() *Command {
 			Short: "Display commands for retrieving resource action history",
 			Long: `The sub-commands of ` + "`" + `doctl compute action` + "`" + ` retrieve the history of actions taken on your resources.
 
-This can be filtered to a specific action. For example, while ` + "`" + `doctl compute action list` + "`" + ` will list all of the actions taken on all of the resources in your account, ` + "`" + `doctl compute action get <action-id>` + "`" + ` will retrieve details for a specific action.`,
+You can retrieve information for a specific action by adding the action's ID as an argument. For example, while ` + "`" + `doctl compute action list` + "`" + ` lists all of the actions taken on all of the resources in your account, ` + "`" + `doctl compute action get <action-id>` + "`" + ` retrieves details for a specific action. Additionally, you can use ` + "`" + `--action-type` + "`" + ` flag to filter the list of actions by type. For example, ` + "`" + `doctl compute action list --action-type power_on` + "`" + ` lists all of the actions that powered on a resource. `,
 		},
 	}
 
 	actionDetails := `
 
 - The action ID
 - The action status (` + "`" + `pending` + "`" + `, ` + "`" + `completed` + "`" + `, etc)
-- The action type (` + "`" + `create` + "`" + `, ` + "`" + `destroy` + "`" + `, ` + "`" + `power_cycle` + "`" + `, ` + "`" + `power_off` + "`" + `, ` + "`" + `power_on` + "`" + `, ` + "`" + `backup` + "`" + `, ` + "`" + `migrate` + "`" + `, ` + "`" + `attach_volume` + "`" + `, etc)
+- The action type, such as: ` + "`" + `create` + "`" + `, ` + "`" + `destroy` + "`" + `, ` + "`" + `power_cycle` + "`" + `, ` + "`" + `power_off` + "`" + `, ` + "`" + `power_on` + "`" + `, ` + "`" + `backup` + "`" + `, ` + "`" + `migrate` + "`" + `, ` + "`" + `attach_volume` + "`" + `
 - The Date/Time when the action started, in RFC3339 format
 - The Date/Time when the action completed, in RFC3339 format
 - The resource ID of the resource upon which the action was taken
 - The resource type (Droplet, backend)
 - The region in which the action took place (nyc3, sfo2, etc)`
 
-	CmdBuilder(cmd, RunCmdActionGet, "get <action-id>", "Retrieve details about a specific action", `This command retrieves the following details about a specific action taken on one of your resources:`+actionDetails, Writer,
+	cmdActionGet := CmdBuilder(cmd, RunCmdActionGet, "get <action-id>", "Retrieve details about a specific action", `Retrieve the following details about a specific action taken on one of your resources:`+actionDetails, Writer,
 		aliasOpt("g"), displayerType(&displayers.Action{}))
+	cmdActionGet.Example = `The following example retrieves the action's ID, status, and resource type of the action with ID 123456: doctl compute action get 123456 --format ID,Status,ResourceType`
 
-	cmdActionList := CmdBuilder(cmd, RunCmdActionList, "list", "Retrieve a  list of all recent actions taken on your resources", `This command retrieves a list of all actions taken on your resources. The following details are provided:`+actionDetails, Writer,
+	cmdActionList := CmdBuilder(cmd, RunCmdActionList, "list", "Retrieve a  list of all recent actions taken on your resources", `Retrieve a list of all actions taken on your resources. The following details are provided:`+actionDetails, Writer,
 		aliasOpt("ls"), displayerType(&displayers.Action{}))
-	AddStringFlag(cmdActionList, doctl.ArgActionResourceType, "", "", "Action resource type")
-	AddStringFlag(cmdActionList, doctl.ArgActionRegion, "", "", "Action region")
-	AddStringFlag(cmdActionList, doctl.ArgActionAfter, "", "", "Action completed after in RFC3339 format")
-	AddStringFlag(cmdActionList, doctl.ArgActionBefore, "", "", "Action completed before in RFC3339 format")
-	AddStringFlag(cmdActionList, doctl.ArgActionStatus, "", "", "Action status")
-	AddStringFlag(cmdActionList, doctl.ArgActionType, "", "", "Action type")
+	AddStringFlag(cmdActionList, doctl.ArgActionResourceType, "", "", `Filter by action resource type, such as `+"`"+`droplet`+"`"+``)
+	AddStringFlag(cmdActionList, doctl.ArgActionRegion, "", "", `Filter by a specified datacenter region, such as `+"`"+`nyc`+"`"+``)
+	AddStringFlag(cmdActionList, doctl.ArgActionAfter, "", "", "Filter actions taken after a specified date, in RFC3339 format.")
+	AddStringFlag(cmdActionList, doctl.ArgActionBefore, "", "", "Filter actions taken after a specified date, in RFC3339 format.")
+	AddStringFlag(cmdActionList, doctl.ArgActionStatus, "", "", `Filter by action status, such as `+"`"+`completed`+"`"+` or `+"`"+`in-progress`+"`"+`.`)
+	AddStringFlag(cmdActionList, doctl.ArgActionType, "", "", `Filter by action type, such as `+"`"+`create`+"`"+` or `+"`"+`destroy`+"`"+``)
+	cmdActionList.Example = `The following command retrieves a list of all the destroy actions taken on the account after October 12, 2022 at 12:00:01 AM UTC, and displays the action ID and region: doctl compute action list --action-type destroy --after 2022-10-12T00:00:01.00Z --format ID,Region`
 
-	cmdActionWait := CmdBuilder(cmd, RunCmdActionWait, "wait <action-id>", "Block thread until an action completes", `The command blocks the current thread, returning when an action completes.
+	cmdActionWait := CmdBuilder(cmd, RunCmdActionWait, "wait <action-id>", "Block thread until an action completes", `Block the current thread, returning when an action completes.
 
 For example, if you find an action when calling `+"`"+`doctl compute action list`+"`"+` that has a status of `+"`"+`in-progress`+"`"+`, you can note the action ID and call `+"`"+`doctl compute action wait <action-id>`+"`"+`, and doctl will appear to "hang" until the action has completed. This can be useful for scripting purposes.`, Writer,
 		aliasOpt("w"), displayerType(&displayers.Action{}))
+	cmdActionWait.Example = `The following example waits for the action ` + "`" + `123456` + "`" + ` to complete before allowing further commands to execute: doctl compute action wait 123456`
 	AddIntFlag(cmdActionWait, doctl.ArgPollTime, "", 5, "Re-poll time in seconds")
 
 	return cmd

commands/activations.go

@@ -43,66 +43,68 @@ func Activations() *Command {
 	cmd := &Command{
 		Command: &cobra.Command{
 			Use:   "activations",
-			Short: "Work with activation records",
-			Long: `The subcommands of ` + "`" + `doctl serverless activations` + "`" + ` will list or retrieve results, logs, or complete
-"activation records" which result from invoking functions deployed to your functions namespace.`,
+			Short: "Retrieve activation records",
+			Long: `The subcommands of ` + "`" + `doctl serverless activations` + "`" + ` retrieve results, logs, or complete
+activation records of functions deployed to your functions namespace.`,
 			Aliases: []string{"activation", "actv"},
 		},
 	}
 
-	get := CmdBuilder(cmd, RunActivationsGet, "get [<activationId>]", "Retrieves an Activation",
-		`Use `+"`"+`doctl serverless activations get`+"`"+` to retrieve the activation record for a previously invoked function.
-There are several options for specifying the activation you want.  You can limit output to the result
+	get := CmdBuilder(cmd, RunActivationsGet, "get [<activationId>]", "Retrieve information about an activation.",
+		`Retrieve the activation record for a previously invoked function. You can limit output to the result
 or the logs.  The `+"`"+`doctl serverless activation logs`+"`"+` command has additional advanced capabilities for retrieving
 logs.`,
 		Writer)
-	AddBoolFlag(get, "last", "l", false, "Fetch the most recent activation (default)")
-	AddIntFlag(get, "skip", "s", 0, "SKIP number of activations")
-	AddBoolFlag(get, "logs", "g", false, "Emit only the logs, stripped of time stamps and stream identifier")
-	AddBoolFlag(get, "result", "r", false, "Emit only the result")
-	AddStringFlag(get, "function", "f", "", "Fetch activations for a specific function")
-	AddBoolFlag(get, "quiet", "q", false, "Suppress last activation information header")
-
-	list := CmdBuilder(cmd, RunActivationsList, "list [<function_name>]", "Lists Activations for which records exist",
+	AddBoolFlag(get, "last", "l", false, "Retrieve the most recent activation (default). Does not return activations for web-invoked functions.")
+	AddIntFlag(get, "skip", "s", 0, "Exclude a specified number of activations from the returned list, starting with the most recent.")
+	AddBoolFlag(get, "logs", "g", false, "Retrieve only the logs, stripped of time stamps and stream identifier.")
+	AddBoolFlag(get, "result", "r", false, "Retrieve only the resulting output of a function.")
+	AddStringFlag(get, "function", "f", "", "Retrieve activations for a specific function.")
+	AddBoolFlag(get, "quiet", "q", false, "Suppress the last activation information header.")
+	get.Example = `The following example retrieves the results for the most recent activation of a function named ` + "`" + `yourFunction` + "`" + `: doctl serverless activations get --function yourFunction --last --result`
+
+	list := CmdBuilder(cmd, RunActivationsList, "list [<function_name>]", "Lists activations for which records exist.",
 		`Use `+"`"+`doctl serverless activations list`+"`"+` to list the activation records that are present in the cloud for previously
 invoked functions.`,
 		Writer,
 		aliasOpt("ls"),
 		displayerType(&displayers.Activation{}),
 	)
-	AddIntFlag(list, "limit", "l", 30, "only return LIMIT number of activations (default 30, max 200)")
-	AddIntFlag(list, "skip", "s", 0, "exclude the first SKIP number of activations from the result")
-	AddIntFlag(list, "since", "", 0, "return activations with timestamps later than SINCE; measured in milliseconds since Th, 01, Jan 1970")
-	AddIntFlag(list, "upto", "", 0, "return activations with timestamps earlier than UPTO; measured in milliseconds since Th, 01, Jan 1970")
-	AddBoolFlag(list, "count", "", false, "show only the total number of activations")
-	AddBoolFlag(list, "full", "f", false, "include full activation description")
-
-	logs := CmdBuilder(cmd, RunActivationsLogs, "logs [<activationId>]", "Retrieves the Logs for an Activation",
+	AddIntFlag(list, "limit", "l", 30, "Limit the number of activations returned to the specified amount. Default: 30, Maximum: 200")
+	AddIntFlag(list, "skip", "s", 0, "Exclude a specified number of activations from the returned list, starting with the most recent.")
+	AddIntFlag(list, "since", "", 0, "Retrieve activations invoked after the specified date-time, in UNIX timestamp format measured in milliseconds.")
+	AddIntFlag(list, "upto", "", 0, "Retrieve activations invoked before the specified date-time; in UNIX timestamp format measured in milliseconds.")
+	AddBoolFlag(list, "count", "", false, "Return only the total number of activations.")
+	AddBoolFlag(list, "full", "f", false, "Include the full activation description.")
+	list.Example = `The following example lists all of the activations for a function named ` + "`" + `yourFunction` + "`" + ` since January 1, 2023: doctl serverless activations list --function yourFunction --since 1672549200000`
+
+	logs := CmdBuilder(cmd, RunActivationsLogs, "logs [<activationId>]", "Retrieve the logs for an activation.",
 		`Use `+"`"+`doctl serverless activations logs`+"`"+` to retrieve the logs portion of one or more activation records
 with various options, such as selecting by package or function, and optionally watching continuously
 for new arrivals.`,
 		Writer)
-	AddStringFlag(logs, "function", "f", "", "Fetch logs for a specific function")
-	AddStringFlag(logs, "package", "p", "", "Fetch logs for a specific package")
-	AddBoolFlag(logs, "last", "l", false, "Fetch the most recent activation logs (default)")
-	AddIntFlag(logs, "limit", "n", 1, "Fetch the last LIMIT activation logs (up to 200)")
-	AddBoolFlag(logs, "strip", "r", false, "strip timestamp information and output first line only")
-	AddBoolFlag(logs, "follow", "", false, "Fetch logs continuously")
+	AddStringFlag(logs, "function", "f", "", "Retrieve the logs for a specific function.")
+	AddStringFlag(logs, "package", "p", "", "Retrieve the logs for a specific package.")
+	AddBoolFlag(logs, "last", "l", false, "Retrieve logs for the most recent activation (default).")
+	AddIntFlag(logs, "limit", "n", 1, "Limit the number of logs returned to the specified amount, up to 200.")
+	AddBoolFlag(logs, "strip", "r", false, "Retrieves only the first line of output in the log, stripped of time stamps.")
+	AddBoolFlag(logs, "follow", "", false, "Continuously return log information.")
+	logs.Example = `The following example retrieves the logs for the most recent activation of a function named ` + "`" + `yourFunction` + "`" + `: doctl serverless activations logs --function yourFunction --last`
 
 	// This is the default behavior, so we want to prevent users from explicitly using this flag. We don't want to remove it
 	// to maintain backwards compatibility
 	logs.Flags().MarkHidden("last")
 
-	result := CmdBuilder(cmd, RunActivationsResult, "result [<activationId>]", "Retrieves the Results for an Activation",
-		`Use `+"`"+`doctl serverless activations result`+"`"+` to retrieve just the results portion
+	result := CmdBuilder(cmd, RunActivationsResult, "result [<activationId>]", "Retrieve the output for an activation.",
+		`Retrieve just the results portion
 of one or more activation records.`,
 		Writer)
-	AddBoolFlag(result, "last", "l", false, "Fetch the most recent activation result (default)")
-	AddIntFlag(result, "limit", "n", 1, "Fetch the last LIMIT activation results (default 30, max 200)")
-	AddIntFlag(result, "skip", "s", 0, "SKIP number of activations")
-	AddStringFlag(result, "function", "f", "", "Fetch results for a specific function")
-	AddBoolFlag(result, "quiet", "q", false, "Suppress last activation information header")
-
+	AddBoolFlag(result, "last", "l", false, "Retrieve the most recent activation result (default).")
+	AddIntFlag(result, "limit", "n", 1, "Limit the number of results return to the specified number. (default 30, max 200)")
+	AddIntFlag(result, "skip", "s", 0, "Exclude a specified number of activations from the returned list, starting with the most recent.")
+	AddStringFlag(result, "function", "f", "", "Retrieve the results for a specific function.")
+	AddBoolFlag(result, "quiet", "q", false, "Suppress last activation information header.")
+	result.Example = `The following example retrieves the results for the most recent activation of a function named ` + "`" + `yourFunction` + "`" + `: doctl serverless activations result --function yourFunction --last`
 	return cmd
 }