I would like some thought given to making the API simple, understandable and convenient.
I agree. At first, I couldn't figure out wait_click(), so I wrote a key handling routine in Lua using is_pressed(). It should be easier than that.
From computer keyboard programming, a key is either UP or DOWN. The key is "pressed" when it goes from UP to DOWN. The key repeats by holding it down after it's pressed. A key click would be UP DOWN UP, but that's not used much for reading computer keyboards. You process a key input when it goes from up to down.
A CHDK "clicked" key looks like it means UP to DOWN. So with CHDK, "pressed" is actually what I would call "DOWN", and "clicked" is what I call "pressed."
Anyway, for consistency, I would add the function:
The option would specify auto repeat, or clear the keyboard buffer, and if half_press is a key or a modifier.