Doesn't zsh do something like this? At the very least, it seems to be extensible enough that you could provide completion+manpage documentation if you wanted to.
Here's what my autocompletion looks like: http://leukensis.org/files/zsh-autocomplete.png
The program has to provide its autocomplete files, but it's very powerful. My 'kill' autocompletes with a ps-like output, for example.