Your casual conversation may make sense to you, but you'll confuse your reader.

My point is not a casual one even if my explanation has failed to be as clear as I would like. Allow me to try to explain it to you as it is fundamentally about documentation, and your skill at technical writing is unquestionable.

When I document that a sub of mine "returns an array", I mean very specifically that the expression supplied to return() (be it explicit or implicit) is an array.

My use of the word "return" corresponds directly to the Perl keyword "return" without trying to describe what return() itself actually does. This is a considered choice, not laziness or lack of understanding.

The behavior of return() is not within my purview. Isn't it to my own benefit to avoid describing it? Don't I, in fact, have a responsibility to yield to its proper documentation?

Granted this is unlikely, but for the sake of argument consider the possibility of return()'s behavior changing. Imagine that a boolean context and a couple boolean values are added to the language. (Yes, it is a ridiculous notion but bare with me.) By not attempting to enumerate every context in the first place, haven't I insulated my own documentation from the change and avoided the need for edits?

I believe this to be a fine documentation strategy. It is simple and allows me to be brief, describe the code itself, and communicate exactly what to expect. It avoids redundancy and protects the documentation, the published interface, from outside changes. It ignores the sometimes sticky issue of context which, really, should not have to reappear in every function's documentation. For these reasons, I will continue to use it.

The one concern that I do have is that it seems several people are confused by it. I find this disconcerting as it is really quite simple. My only explanation is that many people are either too focused on their knowledge of Perl's inner workings or are hung up on documenting their own functions like Perl builtins. (Builtins aren't coded in Perl and hence, it wouldn't make sense to refer to the return keyword in their documentation; this is true of XS code as well.) Whatever the case, this kind of confusion seems to be prevalent wherever lists and list context are discussed. Maybe people still aren't comfortable with the concepts and want to be reminded of the specifics at every turn.

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