docs(api-and-naming): start exporter local var names with underscores

Exporter functions must avoid conflicts between the passed variable
names and their internal local variables. Differentiate using an
underscore.

#539 (comment)

Author: scop

doc/api-and-naming.md

@@ -3,13 +3,14 @@
 Due to its nature, bash-completion adds a number of functions and variables in
 the shell's environment.
 
-|                                | `bash_completion`   | `completions/*`                                                            |
-| :----------------------------- | :------------------ | :------------------------------------------------------------------------- |
-| public configuration variables | `BASH_COMPLETION_*` | `BASH_COMPLETION_CMD_${Command^^}_${Config^^}`                             |
-| non-local internal variables   | `_comp__*`          | `_comp_cmd_${Command}__${Data}`                                            |
-| public/exported functions      | `_comp_*`           | `_comp_cmd_${Command}` (functions for `complete -F`)                       |
-|                                |                     | `_comp_xfunc_${Command}_${Utility}` (functions for use with `_comp_xfunc`) |
-| private/internal functions     | `_comp__*`          | `_comp_cmd_${Command}__${Utility}` (utility functions)                     |
+|                                   | `bash_completion`   | `completions/*`                                                            |
+| :-------------------------------- | :------------------ | :------------------------------------------------------------------------- |
+| public configuration variables    | `BASH_COMPLETION_*` | `BASH_COMPLETION_CMD_${Command^^}_${Config^^}`                             |
+| non-local internal variables      | `_comp__*`          | `_comp_cmd_${Command}__${Data}`                                            |
+| exporter function local variables | `_*` (not `_comp*`) | `_*` (not `_comp*`)                                                        |
+| public/exported functions         | `_comp_*`           | `_comp_cmd_${Command}` (functions for `complete -F`)                       |
+|                                   |                     | `_comp_xfunc_${Command}_${Utility}` (functions for use with `_comp_xfunc`) |
+| private/internal functions        | `_comp__*`          | `_comp_cmd_${Command}__${Utility}` (utility functions)                     |
 
 `${Command}` refers to a command name (with characters not allowed in POSIX
 function or variable names replaced by an underscore), `${Config}` the name of
@@ -38,6 +39,11 @@ sharing a common prefix. For example, a function named `_comp_foo` is "allowed"
 to access `_comp_foo__*` where `*` does not contain any double underscores,
 i.e. it should not access `_comp_foo__something__*` despite the common prefix.
 
+Internal local variables of functions that "export" their results using a
+variable name that is passed in start with an underscore and do not start with
+`_comp`. The variable names that are passed in for this purpose must not start
+with an underscore.
+
 Functions with names prefixed with `_comp_xfunc_` are intended to be used
 through the `_comp_xfunc` function from files other than the one they are
 defined in. From the same file they can be used directly using their complete