Zsh Mailing List Archive
Messages sorted by: Reverse Date, Date, Thread, Author

[PATCH] Update completion style guide

Some additions to the completion style guide based on the comments here:


I haven't seen anyone else complain about the superfluous descriptions, so
maybe i'm editorialising a bit, but hopefully it's reasonable?


diff --git a/Etc/completion-style-guide b/Etc/completion-style-guide
index af7c46bfd..53d522764 100644
--- a/Etc/completion-style-guide
+++ b/Etc/completion-style-guide
@@ -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'
+  '--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 -/ "$@" -

Messages sorted by: Reverse Date, Date, Thread, Author