Cool! I'll definitely check this out.
As for the command name, I agree with @ktoso.
CLI interfaces are full of abbreviations - and while it may not always be completely clear, I much prefer typing
"cp -R" over
"copyFile --recursive", or
"moveFile". Even with things like compiler flags, I much prefer the brevity of
"swiftc -O" over
"compileSwiftCode --enable-all-optimizations" or whatever it would be if we dogmatically chased clarity over brevity even here.
It's important to consider the audience - which kinds of people will even use the CLI interface, and for which purposes? And are those people likely to favour longer, verbose names, or abbreviated names in that context?
IMO, it's one of those things where, abstractly, sure - something like
swift doc or
swift package doc is not 100% clear. But if we went with that name, people who are used to CLI interfaces will appreciate it, and I expect we will get basically zero complaints about it.
Auto-complete is nice, but (in my experience) it's slow, doesn't work everywhere, and I'm not sure it's really practical for command plugins (where the set of available commands depends on the package you're in).
P.S. Also, it's worth remembering that verbose names are particularly difficult for users who do not have English as their first language. The name
generate-documentation has very little meaning to them, and is just a pain to type; like if you were forced to repeatedly type the command name