doc(api-and-naming): add rules for xfuncs and generators

[akinomyoga]

Document the naming rules and implementation advices for xfuncs and _comp_compgen_NAME

#954 (comment)
#964
#962 (comment)

Note: _comp_compegn [-i CMD|-x CMD] are not yet impl;emented.

[scop]

Looks mostly good to me, just a few small comments.

Kind of a head scratcher is that per this definition, I guess the majority of functions would actually be generators, and we'd be up for another round of renamings to bring them up to spec 🤔

Another thing is choosing between options 2 and 3 for internal generators per #962 (reply in thread)

[akinomyoga]

Kind of a head scratcher is that per this definition, I guess the majority of functions would actually be generators, and we'd be up for another round of renamings to bring them up to spec 🤔

For the utility functions defined in bash_completion, I was thinking about adjusting them at the same time as the renaming. E.g., directly renaming _filedir => _comp_compgen_filedir instead of _filedir => _comp_filedir => _comp_compgen_filedir. For other functions defined in specific completion files, as far as the function is used only in a particular way (e.g., the target is fixed to be COMPREPLY, etc.), I was thinking that they don't necessarily need to be updated to be generators soon.

Another thing is choosing between options 2 and 3 for internal generators per #962 (reply in thread)

I left a comment at #962 (reply in thread).

[akinomyoga]

9cd10f7 I added an implementation of -i cmd and -x cmd (along with other minor fixes 8ae00a8, 5e6cbf4).

[scop]

Looks good to me, pre-approved after addressing the apparent conflict in the docs with regards to referencing/modifying target vars in generators.

[scop]

Cheers 👍

[akinomyoga]

Thanks!