compgen -C not working as I expected

[Curious Costanza]

I'm a newcomer to the bug-bash mailing list; I apologize in advance if this 
isn't the appropriate forum for this type of question. I suspect this isn't a 
bug, but I'm very confused about the purpose of the -C option for the compgen 
builtin. As the warning message states, it's not working as I expected. I 
posted a question about this to unix.stackexchange.com. Here is a link to the 
post:


http://unix.stackexchange.com/questions/117987/compgen-warning-c-option-not-working-as-i-expected/

And here is what I posted:

What is the correct way to use the compgen -C option?

I'm trying to learn about Bash programmable completion, and in particular the 
compgen builtin function. I'm experimenting with the different compgen 
command-line options, and I don't understand how the -C flag is supposed to 
work. From the GNU Bash Reference Manual:

    -C command

        command is executed in a subshell environment, and its output is used 
as the possible completions.

Based on this, I expect something like the following to work:

$ compgen -C 'echo "first_option second_option"' f
first_option

But instead, I get this:

$ compgen -C 'echo "first_option second_option"' f
-bash: compgen: warning: -C option may not work as you expect
first_option second_option  f

I've tried this with Bash version 4.2.45 on OS X 10.7 and with Bash version 
4.2.25 on Ubuntu 12.04, and in both cases I get the same error:

-bash: compgen: warning: -C option may not work as you expect


How *should* I expect the -C option to work? What is it's purpose? Where is 
it's use documented?

Thanks in advanced.