Juerd, I am perfectly aware that functions always return a list. Does that mean I'm going to stop documenting that a function like sub f { return 0 } "returns a scalar?"

No.

Somehow I doubt you'd take issue with that even though it isn't technically true. That function is, afterall, returning a list. The list simply has one element. Your argument, if applied evenly, would require the abolishment of the phrase "returns a scalar" as well. Fortunately, we won't have to do that, because your position is completely untenable.

By saying your function "returns a scalar" or "returns an array" or "returns a list" you are able to describe exactly how code the is written without trying to describe how Perl works.

The reason it makes sense to say those things is that context is imposed before the value is returned. When you return @ret; the list returned is composed of elements generated by evaluating @ret in the required context. If it is in scalar context, you get the number of elements of @ret. If it is in list context, you get all of the elements of @ret. Likewise, if you return (33, 42); the list returned is created by evaluating (33, 42) in scalar or list context as necessary.

In other words, there is always a disconnect between what you return and what Perl returns. If you return (33, 42); and your function is called in scalar context, the function returns (42).

I document what I do. Perl is already well-documented.

-sauoq
"My two cents aren't worth a dime.";