docs(api-and-naming: clarify modifications to target variable

Author: akinomyoga

doc/api-and-naming.md

@@ -145,7 +145,8 @@ 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.  One should not directly modify or
+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[@]}"`.
@@ -166,9 +167,11 @@ The exit status is implementation-defined.
   `_comp_compgen_help || _comp_compgen_usage`.
 
 Whether to clear the target variable on runtime error (when `-a` is not
-specified in `OPTS`) is implementation-defined. On the other hand, the
+specified in `OPTS`) is implementation-defined.  On the other hand, the
 generator function should not leave any side effects in the target variable on
-usage error.
+usage error.  Note that the target variable might be cleared by the internal
+calls of `_comp_compgen`.  To explicitly clear the target variable,
+`_comp_compgen_set` can be called without arguments.
 
 Exported generators are defined with the names `_comp_xfunc_CMD_compgen_NAME`
 and called by `_comp_compgen [opts] -x CMD NAME args`.  Internal generators are