Agreed 
I guess the takeaway is to ignore the by keyword altogether, which wouldn’t be that bad imho. It just needs a tiny nudge in the right direction in the docstrings of these functions.
Gotta check if there’s an issue set for 2.0… Edit: found nothing, may write something when I have time