Yeah, I stared down the documentation, implementation, and tests for quite a while before I got it.
I even found a bug or two in the test coverage before noticing that it is the upper not matching the input. 
If you have ideas how to improve the documentation, I think it might well be worth it.
It’s a bit tricky with all the options.