Updates doc strings and adds examples for Reserved IP commands

commands/reserved_ips.go

@@ -31,34 +31,38 @@ func ReservedIP() *Command {
 			Use:   "reserved-ip",
 			Short: "Display commands to manage reserved IP addresses",
 			Long: `The sub-commands of ` + "`" + `doctl compute reserved-ip` + "`" + ` manage reserved IP addresses.
-Reserved IPs are publicly-accessible static IP addresses that can be mapped to one of your Droplets. They can be used to create highly available setups or other configurations requiring movable addresses. Reserved IPs are bound to a specific region.`,
+Reserved IPs are publicly-accessible static IP addresses that you can to one of your Droplets. They can be used to create highly available setups or other configurations requiring movable addresses. Reserved IPs are bound to the regions they are created in.`,
 			Aliases: []string{"fip", "floating-ip", "floating-ips", "reserved-ips"},
 		},
 	}
 
-	cmdReservedIPCreate := CmdBuilder(cmd, RunReservedIPCreate, "create", "Create a new reserved IP address", `Use this command to create a new reserved IP address.
+	cmdReservedIPCreate := CmdBuilder(cmd, RunReservedIPCreate, "create", "Create a new reserved IP address", `Creates a new reserved IP address.
 
-A reserved IP address must be either assigned to a Droplet or reserved to a region.`, Writer,
+Reserved IP addresses can either be assigned to Droplets or held in the region they were created in on your account, but because of the IPv4 address shortage, unassigned reserved IP addresses incur charges.`, Writer,
 		aliasOpt("c"), displayerType(&displayers.ReservedIP{}))
 	AddStringFlag(cmdReservedIPCreate, doctl.ArgRegionSlug, "", "",
-		fmt.Sprintf("Region where to create the reserved IP address. (mutually exclusive with `--%s`)",
+		fmt.Sprintf("The region where to create the reserved IP address. Cannot be used with the `--%s` flag.",
 			doctl.ArgDropletID))
 	AddStringFlag(cmdReservedIPCreate, doctl.ArgProjectID, "", "",
-		fmt.Sprintf("The ID of the project the reserved IP address will be assigned to. When excluded, it will be assigned to the default project. When using the `--%s` flag, it will be assigned to the project containing the Droplet.",
+		fmt.Sprintf("The ID of the project to assign the IP address. When excluded, the address is assigned to your default project. When using the `--%s` flag, it is assigned to the project containing the Droplet.",
 			doctl.ArgDropletID))
 	AddIntFlag(cmdReservedIPCreate, doctl.ArgDropletID, "", 0,
-		fmt.Sprintf("The ID of the Droplet to assign the reserved IP to (mutually exclusive with `--%s`).",
+		fmt.Sprintf("The ID of the Droplet to assign the reserved IP to. Cannot be used with the `--%s` flag.",
 			doctl.ArgRegionSlug))
+	cmdReservedIPCreate.Example = `The following example creates a reserved IP address in the ` + "`" + `nyc1` + "`" + ` region and assigns it to a Droplet with the ID ` + "`" + `386734086` + "`" + `: doctl compute reserved-ip create --region nyc1 --droplet-id 386734086`
 
-	CmdBuilder(cmd, RunReservedIPGet, "get <reserved-ip>", "Retrieve information about a reserved IP address", "Use this command to retrieve detailed information about a reserved IP address.", Writer,
+	cmdReservedIPGet := CmdBuilder(cmd, RunReservedIPGet, "get <reserved-ip>", "Retrieve information about a reserved IP address", "Retrieves detailed information about a reserved IP address, including its region and the ID of the Droplet its assigned to.", Writer,
 		aliasOpt("g"), displayerType(&displayers.ReservedIP{}))
+	cmdReservedIPGet.Example = `The following example retrieves information about the reserved IP address ` + "`" + `203.0.113.25` + "`" + `: doctl compute reserved-ip get 203.0.113.25`
 
-	cmdRunReservedIPDelete := CmdBuilder(cmd, RunReservedIPDelete, "delete <reserved-ip>", "Permanently delete a reserved IP address", "Use this command to permanently delete a reserved IP address. This is irreversible.", Writer, aliasOpt("d", "rm"))
-	AddBoolFlag(cmdRunReservedIPDelete, doctl.ArgForce, doctl.ArgShortForce, false, "Force reserved IP delete")
+	cmdRunReservedIPDelete := CmdBuilder(cmd, RunReservedIPDelete, "delete <reserved-ip>", "Permanently delete a reserved IP address", "Permanently deletes a reserved IP address. This is irreversible.", Writer, aliasOpt("d", "rm"))
+	AddBoolFlag(cmdRunReservedIPDelete, doctl.ArgForce, doctl.ArgShortForce, false, "Deletes the reserved IP address without confirmation")
+	cmdRunReservedIPDelete.Example = `The following example deletes the reserved IP address ` + "`" + `203.0.113.25` + "`" + `: doctl compute reserved-ip delete 203.0.113.25`
 
-	cmdReservedIPList := CmdBuilder(cmd, RunReservedIPList, "list", "List all reserved IP addresses on your account", "Use this command to list all the reserved IP addresses on your account.", Writer,
+	cmdReservedIPList := CmdBuilder(cmd, RunReservedIPList, "list", "List all reserved IP addresses on your account", "Retrieves a list of all the reserved IP addresses on your account.", Writer,
 		aliasOpt("ls"), displayerType(&displayers.ReservedIP{}))
-	AddStringFlag(cmdReservedIPList, doctl.ArgRegionSlug, "", "", "The region the reserved IP address resides in")
+	AddStringFlag(cmdReservedIPList, doctl.ArgRegionSlug, "", "", "Retrieves a list of reserved IP addresses in the specified region")
+	cmdReservedIPList.Example = `The following example lists all reserved IP addresses in the ` + "`" + `nyc1` + "`" + ` region: doctl compute reserved-ip list --region nyc1`
 
 	return cmd
 }