mirrors/zsh
1
0
Fork 0
mirror of git://git.code.sf.net/p/zsh/code synced 2025-10-26 04:30:27 +01:00
Code Releases Activity

44969: completion-style-guide: Mention defaults and superfluous descriptions

Browse source
This commit is contained in:
dana 2019-12-02 17:29:45 -06:00
parent 0c59705e9e
commit 3aa53d1248
2 changed files with 27 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

3
ChangeLog
View file

@ -1,5 +1,8 @@
2019-12-02 dana <dana@dana.is>
* 44969: Etc/completion-style-guide: Mention defaults and
superfluous descriptions
* unposted (cf. 44967): Completion/Linux/Command/_alsa-utils:
Fix minor syntax error in arg spec

25
Etc/completion-style-guide
View file

@ -69,12 +69,35 @@ for example, do not use:
'--timeout[specify connection timeout in milliseconds]:timeout'
but use:
'--timeout[specify connection timeout]:timeout (ms)'
To indicate a default value, use square brackets:
'--timeout[specify connection timeout]:timeout (ms) [5000]'
These two conventions can be used together or individually as appropriate.
Group descriptions should be singular because only one thing is being
completed even though many may be listed. This applies even where you
complete a list of the things. Tags, functions for completing types of
things (such as _files), and states should have plural names.
Group descriptions can be omitted where they are handled by a helper/type
function. For example, the `file' description in the following line is
unnecessary, as `_files' provides it by default:
'--import=[import specified file]:file:_files'
In this case, the following syntax can be used instead:
'--import=[import specified file]: :_files'
Of course, it may make sense to add an explicit description which is
more specific than the default:
'--config=[use specified config file]:config file:_files'
Similarly, group descriptions can and should be omitted where a `->state'
is involved, as the description in the argument spec is always ignored
in these cases. For example, instead of:
'--config=[use specified config file]:config file:->config-files'
use:
'--config=[use specified config file]: :->config-files'
Setting an explicit description here constitutes (a small amount of)
unnecessary noise, and may be misleading to other developers who update
the function.
In a function, allow any descriptions passed as an argument to override
the default you define. For example:
_wanted directories expl directory _files -/ "$@" -