docs: improve command usage documentation

[phm07]

This PR makes command usage documentation consistent by enforcing docopt rules and also defining and documenting other additional conventions.

Fixes #708

[codecov]

Codecov Report

Attention: Patch coverage is 91.01124% with 8 lines in your changes are missing coverage. Please review.

Project coverage is 58.77%. Comparing base (4712950) to head (9457dc5).
Report is 2 commits behind head on main.

Files	Patch %	Lines
internal/cmd/base/delete.go	50.00%	1 Missing and 1 partial ⚠️
internal/cmd/base/labels.go	0.00%	2 Missing ⚠️
internal/cmd/base/set_rdns.go	0.00%	1 Missing ⚠️
internal/cmd/base/update.go	0.00%	1 Missing ⚠️
internal/cmd/server/enable_protection.go	0.00%	1 Missing ⚠️
internal/cmd/server/ssh.go	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #709      +/-   ##
==========================================
- Coverage   58.78%   58.77%   -0.02%     
==========================================
  Files         179      179              
  Lines        6536     6539       +3     
==========================================
+ Hits         3842     3843       +1     
- Misses       2087     2088       +1     
- Partials      607      608       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[jooola]

Not sure to understand this, the main difference between multiple arguments is their position, so moving them around would be a breaking change.

EDIT: are you referring to flags/options ? For me flags/options != arguments.

Was weird that you wrote optional arguments, as they are 'required' by definition.

But yeah, I'd rather have the arguments first, and the options after. What does docopts say?

[phm07]

Sorry, you're right, I meant flags there. Docopt doesn't say anything about argument/flag order. Having optional flags first, then arguments and then required flags made the most sense to me because then the ordering would be most specific to least specific.

[phm07]

About the ordering, this is what the CLI Guidelines have to say: https://clig.dev/#help
They suggest putting the [options] first as well (like jq and git do it too for example). But generally they put all flags first (even required ones) and the positional arguments last, while we do optional flags < positional args < required flags. Maybe we can move the positional args all the way to the back like jq does.
On the other hand, if you look here for example, positional args would be easily overlooked if they are placed last. What's your opinion on this?

[jooola]

I would always try to have the required and optional flags next to each other, having the arguments in the middle seem weird.

Whether we put the arguments at the beginning or the end, I think I prefer at the beginning. When I write a command, I prefer to go in order of importance <resource type> <actions> <resource id> <resource fields (e.g. labels)>. Having the flags before also seem weird.

[apricote]

I do not have a strong opinion on this.

While using the CLI I use the same mental model as @jooola and also put <args> <req flags> <optional flags>.

[phm07]

I reordered the usage strings in 4ffc625. It is now in line with the CLI guideline suggestions

[apricote]

It looks like you only committed some of the changes, there are still many files with old order, for example internal/cmd/loadbalancer/update_service.go or internal/cmd/firewall/remove_from_resource.go

[phm07]

Yes, I totally forgot to commit the changes, I did not just not see them ^^
Fixed in 9457dc5

[apricote]

Very nice!