added API documentation of available bash_completion methods

[meridius]

Since there is no reliable utility to auto-generate documentation by parsing the shell script itself I had to do grep -e "^#" --color=none -A1 /usr/share/bash-completion/bash_completion > API.md and edit it manually. It violates the Single Source of Truth principle but it's better than nothing.

[scop]

This is good stuff, however I'm somewhat unsure of it because of two issues. I'm not saying I'm rejecting it, just explaining why it might take some time to apply something like this.

1. As you noted, single source of truth, and therefore maintenance considerations.
2. A few years back, we had a discussion what constitutes the bash-completion API in the first place. Nobody actually has decided that. What is fairly certain though, is that all functions are not guaranteed to be part of a stable API, and in theory can change, even though it won't be done lightly. So I'm a bit worried that if the entire API is documented more prominently like it is here, it gives a possibly false impression of the stability of the API. I'm not sure what to do about this.

[meridius]

I get your worries about added maintenance cost. But I still think it's better to give users something they can work with, which will ease the development of new completions. It's really a pain to go through all the code trying to find the one function you need, at least from my point of view.

As for the API stability. I'd say the API is pretty stable since there already are completions using the functions. ;) But hey, how about we stated in the documentation that it is valid for a specific version of bash-completion. It's OK for documentation to fall behind a bit after the code for lots of reasons. If user wants to check the current API, they can always look right to the code. We wouldn't be the first project that would do it this way.

What do you think?