Docs/polish command documentation (#63)

* docs(root): remove superfluous and unsupported auto option description from --colours

* docs(ipaddress/modify): clarify --ptr-record

* docs(router/list): remove superfluous default documentation

* docs(server/create): clarify host parameter

* docs(title): make --title documentation consistent

* docs(server/modify): make bootorder documentation match with server create

* docs(networkinterface/creata): --clarify ip-addresses

* docs(networkinterface/modify): --clarify ip-addresses and --new-index

* docs(server/restart): make --stop-type consistent with server stop

* docs(storage/import): add a TODO to source-type

* docs(storage/attach): clarify --address

Co-authored-by: Matias Lahti <[email protected]>

internal/commands/ipaddress/modify.go

@@ -31,7 +31,7 @@ func ModifyCommand() commands.Command {
 func (s *modifyCommand) InitCommand() {
 	fs := &pflag.FlagSet{}
 	fs.StringVar(&s.mac, "mac", "", "MAC address of server interface to attach floating IP to.")
-	fs.StringVar(&s.ptrrecord, "ptr-record", "", "A fully qualified domain name.")
+	fs.StringVar(&s.ptrrecord, "ptr-record", "", "New fully qualified domain name to set as the PTR record for the IP address.")
 	s.AddFlags(fs)
 }
 

internal/commands/networkinterface/create.go

@@ -46,9 +46,10 @@ func (s *createCommand) InitCommand() {
 	fs.IntVar(&s.interfaceIndex, "index", 0, "Interface index.")
 	fs.BoolVar(&s.bootable, "bootable", false, "Whether to try booting through the interface.")
 	fs.BoolVar(&s.sourceIPFiltering, "source-ip-filtering", false, "Whether source IP filtering is enabled on the interface. Disabling it is allowed only for SDN private interfaces.")
-	fs.StringSliceVar(&s.ipAddresses, "ip-addresses", []string{}, "Array of IP addresses, multiple can be declared\n\n"+
-		"Usage: --ip-addresses 94.237.112.143,94.237.112.144")
-	s.AddFlags(fs) // TODO(ana): replace usage with examples once the refactor is done.
+	fs.StringSliceVar(&s.ipAddresses, "ip-addresses", []string{}, "A comma-separated list of IP addresses")
+	// TODO: add to examples when implemented
+	//	"Usage: --ip-addresses 94.237.112.143,94.237.112.144")
+	s.AddFlags(fs)
 }
 
 // MaximumExecutions implements Command.MaximumExecutions

internal/commands/networkinterface/modify.go

@@ -35,11 +35,11 @@ func ModifyCommand() commands.Command {
 func (s *modifyCommand) InitCommand() {
 	fs := &pflag.FlagSet{}
 	fs.IntVar(&s.currentIndex, "index", s.currentIndex, "Index of the interface to modify.")
-	fs.IntVar(&s.newIndex, "new-index", s.newIndex, "Index of the interface to modify.")
+	fs.IntVar(&s.newIndex, "new-index", s.newIndex, "New index to move the interface to.")
 	// TODO: refactor string to tristate bools (eg. allow empty)
 	fs.StringVar(&s.bootable, "bootable", s.bootable, "Whether to try booting through the interface.")
 	fs.StringVar(&s.sourceIPfiltering, "source-ip-filtering", s.sourceIPfiltering, "Whether source IP filtering is enabled on the interface. Disabling it is allowed only for SDN private interfaces.")
-	fs.StringSliceVar(&s.ipAddresses, "ip-addresses", s.ipAddresses, "Array of IP addresses, multiple can be declared\nUsage: --ip-address address=94.237.112.143,family=IPv4")
+	fs.StringSliceVar(&s.ipAddresses, "ip-addresses", s.ipAddresses, "A comma-separated list of IP addresses, multiple can be declared\nUsage: --ip-address address=94.237.112.143,family=IPv4")
 	s.AddFlags(fs) // TODO(ana): replace usage with examples once the refactor is done.
 }
 

internal/commands/router/list.go

@@ -27,7 +27,7 @@ func (s *listCommand) InitCommand() {
 	//	s.header = table.Row{"UUID", "Name", "Type"}
 	flags := &pflag.FlagSet{}
 	flags.BoolVar(&s.allRouters, "all", false, "Show all routers.")
-	flags.BoolVar(&s.normalRouters, "normal", true, "Show normal routers (default).")
+	flags.BoolVar(&s.normalRouters, "normal", true, "Show normal routers.")
 	flags.BoolVar(&s.serviceRouters, "service", false, "Show service routers.")
 	// TODO: reimplement
 	// 	s.AddVisibleColumnsFlag(flags, &s.visibleColumns, s.columnKeys, s.visibleColumns)

internal/commands/server/create.go

@@ -214,13 +214,13 @@ func (s *createCommand) InitCommand() {
 	s.params = createParams{CreateServerRequest: request.CreateServerRequest{}}
 	def := defaultCreateParams
 	fs.IntVar(&s.params.AvoidHost, "avoid-host", def.AvoidHost, "Use this to make sure VMs do not reside on specific host. Refers to value from host -attribute. Useful when building HA-environments.")
-	fs.IntVar(&s.params.Host, "host", def.Host, "Use this to start a VM on a specific host. Refers to value from host -attribute. Only available for private cloud hosts.")
+	fs.IntVar(&s.params.Host, "host", def.Host, "Use this to start a VM on a specific private cloud host. Refers to value from host -attribute. Only available in private clouds.")
 	fs.StringVar(&s.params.BootOrder, "boot-order", def.BootOrder, "The boot device order, disk / cdrom / network or comma separated combination.")
 	fs.StringVar(&s.params.UserData, "user-data", def.UserData, "Defines URL for a server setup script, or the script body itself.")
 	fs.IntVar(&s.params.CoreNumber, "cores", def.CoreNumber, "Number of cores. Use only when defining a flexible (\"custom\") plan.")
 	fs.IntVar(&s.params.MemoryAmount, "memory", def.MemoryAmount, "Memory amount in MiB. Use only when defining a flexible (\"custom\") plan.")
-	fs.StringVar(&s.params.Title, "title", def.Title, "Visible name.")
-	fs.StringVar(&s.params.Hostname, "hostname", def.Hostname, "Hostname.")
+	fs.StringVar(&s.params.Title, "title", def.Title, "A short, informational description.")
+	fs.StringVar(&s.params.Hostname, "hostname", def.Hostname, "Server hostname.")
 	fs.StringVar(&s.params.Plan, "plan", def.Plan, "Server plan name. See \"server plans\" command for valid plans. Set --cores and --memory for a flexible plan.")
 	fs.StringVar(&s.params.os, "os", def.os, "Server OS to use (will be the first storage device). Set to empty to fully customise the storages.")
 	fs.IntVar(&s.params.osStorageSize, "os-storage-size", def.osStorageSize, "OS storage size in GiB. This is only applicable if `os` is also set. Zero value makes the disk equal to the minimum size of the template.")

internal/commands/server/modify.go

@@ -42,15 +42,15 @@ var defaultModifyParams = modifyParams{
 func (s *modifyCommand) InitCommand() {
 	s.params = modifyParams{ModifyServerRequest: request.ModifyServerRequest{}}
 	flags := &pflag.FlagSet{}
-	flags.StringVar(&s.params.BootOrder, "boot-order", defaultModifyParams.BootOrder, "The boot device order.")
+	flags.StringVar(&s.params.BootOrder, "boot-order", defaultModifyParams.BootOrder, "The boot device order, disk / cdrom / network or comma separated combination.")
 	flags.IntVar(&s.params.CoreNumber, "cores", defaultModifyParams.CoreNumber, "Number of cores. Sets server plan to custom.")
 	flags.StringVar(&s.params.Hostname, "hostname", defaultModifyParams.Hostname, "Hostname.")
 	flags.StringVar(&s.params.Firewall, "firewall", defaultModifyParams.Firewall, "Enables or disables firewall on the server. You can manage firewall rules with the firewall command.\nAvailable: true, false")
 	flags.IntVar(&s.params.MemoryAmount, "memory", defaultModifyParams.MemoryAmount, "Memory amount in MiB. Sets server plan to custom.")
 	flags.StringVar(&s.params.metadata, "metadata", defaultModifyParams.metadata, "Enable metadata service.")
 	flags.StringVar(&s.params.Plan, "plan", defaultModifyParams.Plan, "Server plan to use.")
 	flags.StringVar(&s.params.SimpleBackup, "simple-backup", defaultModifyParams.SimpleBackup, "Simple backup rule. Format (HHMM,{dailies,weeklies,monthlies}).\nExample: 2300,dailies")
-	flags.StringVar(&s.params.Title, "title", defaultModifyParams.Title, "Visible name.")
+	flags.StringVar(&s.params.Title, "title", defaultModifyParams.Title, "A short, informational description.")
 	flags.StringVar(&s.params.TimeZone, "time-zone", defaultModifyParams.TimeZone, "Time zone to set the RTC to.")
 	flags.StringVar(&s.params.VideoModel, "video-model", defaultModifyParams.VideoModel, "Video interface model of the server.\nAvailable: vga,cirrus")
 	flags.StringVar(&s.params.remoteAccessEnabled, "remote-access-enabled", defaultModifyParams.remoteAccessEnabled, "Enables or disables the remote access.\nAvailable: true, false")

internal/commands/server/restart.go

@@ -37,7 +37,7 @@ func (s *restartCommand) InitCommand() {
 
 	// TODO: reimplement? does not seem to make sense to automagically destroy
 	// servers if restart fails..
-	flags.StringVar(&s.StopType, "stop-type", defaultStopType, "Restart type. Available: soft, hard")
+	flags.StringVar(&s.StopType, "stop-type", defaultStopType, "The type of stop operation. Available: soft, hard")
 	s.AddFlags(flags)
 }
 

internal/commands/serverstorage/attach.go

@@ -47,7 +47,7 @@ func (s *attachCommand) InitCommand() {
 
 	flagSet := &pflag.FlagSet{}
 	flagSet.StringVar(&s.params.Type, "type", defaultAttachParams.Type, "Type of the attached storage. Available: disk, cdrom")
-	flagSet.StringVar(&s.params.Address, "address", defaultAttachParams.Address, "Address where the storage device is attached on the server. \nSpecify only the bus name (ide/scsi/virtio) to auto-select next available address from that bus.")
+	flagSet.StringVar(&s.params.Address, "address", defaultAttachParams.Address, "Address where the storage device is attached on the server. \nAddress is of the form busname:deviceindex where busname can be ide/scsi/virtio. (example: 'virtio:1')\nSpecify only the bus name to auto-select next available device index from that bus. (example: 'virtio')")
 	flagSet.StringVar(&s.params.StorageUUID, "storage", defaultAttachParams.StorageUUID, "UUID of the storage to attach.")
 	flagSet.BoolVar(&s.params.bootable, "boot-disk", false, "Set attached device as the server's boot disk.")
 

internal/commands/storage/create.go

@@ -64,7 +64,7 @@ type createCommand struct {
 }
 
 func applyCreateFlags(fs *pflag.FlagSet, dst, def *createParams) {
-	fs.StringVar(&dst.Title, "title", def.Title, "Storage title.")
+	fs.StringVar(&dst.Title, "title", def.Title, "A short, informational description.")
 	fs.IntVar(&dst.Size, "size", def.Size, "Size of the storage in GiB.")
 	fs.StringVar(&dst.Zone, "zone", def.Zone, "Physical location of the storage. See zone listing for valid zones.")
 	fs.StringVar(&dst.Tier, "tier", def.Tier, "Storage tier.")

internal/commands/storage/import.go

@@ -64,6 +64,8 @@ type importCommand struct {
 func (s *importCommand) InitCommand() {
 	flagSet := &pflag.FlagSet{}
 	flagSet.StringVar(&s.sourceLocation, "source-location", "", "Location of the source of the import. Can be a file or a URL.")
+	// TODO: is this flag actually required? Could we not just figure it out depending on the location?
+	// eg. if there's a file with the name given in location, use direct upload, otherwise validate url and use http import?
 	flagSet.StringVar(&s.sourceType, "source-type", "", fmt.Sprintf("Source type, is derived from source-location if not given. Available: %s,%s",
 		upcloud.StorageImportSourceHTTPImport,
 		upcloud.StorageImportSourceDirectUpload))

internal/commands/storage/modify.go

@@ -56,7 +56,7 @@ func (s *modifyCommand) InitCommand() {
 	s.params = modifyParams{ModifyStorageRequest: request.ModifyStorageRequest{}}
 
 	flagSet := &pflag.FlagSet{}
-	flagSet.StringVar(&s.params.Title, "title", defaultModifyParams.Title, "Storage title.")
+	flagSet.StringVar(&s.params.Title, "title", defaultModifyParams.Title, "A short, informational description.")
 	flagSet.IntVar(&s.params.Size, "size", defaultModifyParams.Size, "Size of the storage (GiB).")
 	flagSet.StringVar(&s.params.backupTime, "backup-time", s.params.backupTime, "The time when to create a backup in HH:MM. Empty value means no backups.")
 	flagSet.StringVar(&s.params.backupInterval, "backup-interval", "", "The interval of the backup.\nAvailable: daily,mon,tue,wed,thu,fri,sat,sun")

internal/core/bootstrap.go

@@ -55,7 +55,7 @@ func BuildRootCmd(_ []string, conf *config.Config) cobra.Command {
 	)
 	flags.BoolVar(
 		&conf.GlobalFlags.Colors, "colours", true,
-		"Use terminal colours (supported: auto, true, false)",
+		"Use terminal colours",
 	)
 	flags.DurationVarP(
 		&conf.GlobalFlags.ClientTimeout, "client-timeout", "t",