docs: describe uses of _comp_compgen_split

Author: akinomyoga

CONTRIBUTING.md

@@ -117,15 +117,21 @@ Also, please bear the following coding guidelines in mind:
   variables are set (e.g. with `[[ -v varname ]]`) or use default
   expansion (e.g. `${varname-}`).
 
-- Prefer `compgen -W '...' -- $cur` over embedding `$cur` in external
-  command arguments (often e.g. sed, grep etc) unless there's a good
-  reason to embed it. Embedding user input in command lines can result
-  in syntax errors and other undesired behavior, or messy quoting
-  requirements when the input contains unusual characters. Good
-  reasons for embedding include functionality (if the thing does not
-  sanely work otherwise) or performance (if it makes a big difference
-  in speed), but all embedding cases should be documented with
-  rationale in comments in the code.
+- Prefer `_comp_compgen_split -- "$(...)"` over embedding `$cur` in external
+  command arguments (often e.g. sed, grep etc) unless there's a good reason to
+  embed it. Embedding user input in command lines can result in syntax errors
+  and other undesired behavior, or messy quoting requirements when the input
+  contains unusual characters.  Good reasons for embedding include
+  functionality (if the thing does not sanely work otherwise) or performance
+  (if it makes a big difference in speed), but all embedding cases should be
+  documented with rationale in comments in the code.
+
+  Do not use `_comp_compgen -- -W "$(...)"` or `_comp_compgen -- -W '$(...)'`
+  but always use `_comp_compgen_split -- "$(...)"`.  In the former case, when
+  the command output contains strings looking like shell expansions, the
+  expansions will be unexpectedly performed, which becomes a vulnerability.  In
+  the latter case, checks by shellcheck and shfmt will not be performed inside
+  `'...'`.  Also, `_comp_compgen_split` is `IFS`-safe.
 
 - When completing available options, offer only the most descriptive
   ones as completion results if there are multiple options that do the

doc/api-and-naming.md

@@ -145,11 +145,14 @@ specified by `-v var` in `OPTS`).
 ### Implementing a generator function
 
 To implement a generator function, one should generate completion candidates by
-calling `_comp_compgen` or other generators.  To avoid conflicts with the
-options specified to `_comp_compgen`, one should not directly modify or
-reference the target variable.  When post-filtering is needed, store them in
-local arrays, filter them, and finally append them by `_comp_compgen -- -W
-"${arr[@]}"`.
+calling `_comp_compgen` or other generators.
+
+To avoid conflicts with the options specified to `_comp_compgen`, one should
+not directly modify or reference the target variable.  When post-filtering is
+needed, store them in a local array, filter them, and finally append them by
+`_comp_compgen -- -W '"${arr[@]}"'`.  To split the output of commands and
+append the results to the target variable, use `_comp_compgen_split -- "$(cmd
+...)"` instead of using `_comp_split COMPREPLY "$(cmd ...)"`.
 
 A generator function should replace the existing content of the variable by
 default.  When the appending behavior is favored, the caller should specify it