git stash --keep-index doesn't have the expected behaviour

If you search the internet for "git stash only unstaged changes" you can find much misleading information about what "git stash --keep-index" does. However, it is my opinion that the --keep-index option is broken, in that it doesn't do what 90% of people want it to do - that is, stash only the unstaged changes and not include the staged changes in the stash. You can find many hacks to work around this limitation, none of which are very satisfactory.

It was pointed out by some commenters on Stack Overflow that the examples given in the documentation at https://git-scm.com/docs/git-stash imply that the intended behaviour of "git stash --keep-index" is to stash only the unstaged changes. Based on that, they reason that it's actually a bug. I'm not sure that's true, but I find the existing behaviour of "--keep-index" puzzling because I can't think of when I would use it (whereas stashing only unstaged changes is a feature I would frequently use).

Is it possible that --keep-index could be fixed/improved/modified to stash only the unstaged changes, or alternatively a new option introduced which does this?