I'm not sure of the correct behavior, but the implementation and the docs sure don't agree at the moment. One or the other needs to change.

If it's the docs that change, a caveat about old code tested under older versions now changing semantics should be present. That's almost never a good thing to see in your docs.