search

digitalocean / doctl

The official command line interface for the DigitalOcean API.
https://docs.digitalocean.com/reference/doctl/
Apache License 2.0
3.26k stars 396 forks source link

Some inconsistencies in enum argument descriptions #1597

Open zikalino opened 1 month ago

zikalino commented 1 month ago

Describe the Issue:

I have done some more investigation related to this PR: https://github.com/digitalocean/doctl/pull/1595, and I found more related issues / inconsistencies.

For instance in doctl databases topics update:

 --cleanup-policy string              Specifies the retention policy to use on log segments: Possible values are 'delete', 'compact_delete', 'compact' (default "delete")
 --compression-type string            Specifies the compression type for a kafka topic: Possible values are 'producer', 'gzip', 'snappy', 'Iz4', 'zstd', 'uncompressed' (default "producer")

but in doctl databases create and most other places:

--engine pg                          The database's engine. Possible values are: pg, `mysql`, `redis`, `mongodb`, `kafka` and `opensearch`. (default "pg")

In the first example, apostrophes don't interfere with command argument type generation and it stays defined as string. In the second example, backticks are causing to use first value (pg) as data type for argument, which can be confusing.

I would be happy to create PR to fix this, however, I am not sure whether there's any reason attached to using backticks versus apostrophes. I am also not sure why default value is in quotes.

One possible solution is to introduce enum data type, and then argument descriptions could look like this:

--engine enum                          The database's engine. Possible enum values are: `pg`, `mysql`, `redis`, `mongodb`, `kafka` and `opensearch`. (default "pg")
andrewsomething commented 1 month ago

Thanks for looking into this @zikalino!

The one positive to the backticks is that they display as code in the online version of the documentation:

https://docs.digitalocean.com/reference/doctl/reference/databases/create/

I am also not sure why default value is in quotes.

This behavior comes from the Cobra library. For example, notice we specify a default but don't actually add that to the description. Cobra automatically appends the (default "pg"):

https://github.com/digitalocean/doctl/blob/062646883a3a9e3c24cce7d1a43a030a089abc4c/commands/databases.go#L88