The API documentation should reflect that the result is context sensitive. Not reading that is a good way to get burned despite the language.
Perl is well known for it's multitude of idiosyncrasies, this is one of the reasons why it can be frustrating to programmers who have better experience in more modern or rigidly structured languages.