Document $split && return.

1 files changed, 20 insertions, 0 deletions

diff --git a/doc/styleguide.txt b/doc/styleguide.txt
index 12b224f1..31ad4469 100644
--- a/doc/styleguide.txt
+++ b/doc/styleguide.txt
@@ -75,6 +75,26 @@ appended after the equal sign.  Calling compopt -o nospace makes sense
 in case completion actually occurs: when only one completion is
 available in COMPREPLY.
 
+$split && return
+----------------
+
+Should be used in completions using the -s flag of _init_completion,
+or other similar cases where _split_longopt has been invoked, after
+$prev has been managed but before $cur is considered.  If $cur of the
+form --foo=bar was split into $prev=--foo and $cur=bar and the $prev
+block did not process the option argument completion, it makes sense
+to return immediately after the $prev block because --foo obviously
+takes an argument and the remainder of the completion function is
+unlikely to provide meaningful results for the required argument.
+Think of this as a catch-all for unknown options requiring an
+argument.
+
+Note that even when using this, options that are known to require an
+argument but for which we don't have argument completion should be
+explicitly handled (non-completed) in the $prev handling block because
+--foo=bar options can often be written without the equals sign, and in
+that case the long option splitting does not occur.
+
 /////////////////////////////////////////
 case/esac vs if
 ---------------