develooper Front page | perl.perl5.porters | Postings from March 2023

Re: Amending the perlsub documentation about empty returns

Thread Previous
From:
demerphq
Date:
March 12, 2023 15:34
Subject:
Re: Amending the perlsub documentation about empty returns
Message ID:
CANgJU+XsKKs86Wbi4VKJL++6PoZ38VKp-Ox+4XpX0cg6N=Y=pg@mail.gmail.com
On Sun, 12 Mar 2023 at 14:47, Robert Rothenberg <rrwo@cpan.org> wrote:

>
> On 06/03/2023 17:05, Dan Book wrote:
>
> On Mon, Mar 6, 2023 at 11:52 AM Robert Rothenberg <rrwo@cpan.org> wrote:
>
>> The perlsub documentation briefly discusses empty returns:
>>
>>  > If you specify no return value, the subroutine returns an empty list
>> in list context, the undefined value in scalar context, or nothing in
>> void context.
>>
>> This really needs some elaboration on when its good to specify no return
>> value, and when it's not, such as when the return value is on the right
>> side of a fat comma.
>>
>
> That assumes the return and the call are written by the same person or
> even in the same project which is often not the case when such issues occur.
>
> I would assume that the return value of a library would be documented
> enough so that people writing code that uses it would handle it
> appropriately.
>
> But a sentence or two on the danger may be warranted.
>
> I think perlsub needs a larger section on "Return Values" that discusses
> issues with:
>
> - calling context (void, scalar or array), and wantarray
>
> - no return value vs undef
>

So put together a patch and submit a PR[1].

If you are perhaps a little shy about pushing a PR without having some
review first I would be happy to check out what you have done and give you
some feedback.  Just let me know.

Cheers
Yves
[1] I am not being passive-aggressive here, nor in any way snarky.
Ultimately the best way to improve the docs is to write a patch to improve
the docs. If you think it can be improved then get the ball rolling with
some text. The worst that can happen is that someone with more knowledge or
better writing skills decides they can do better and writes their own to
supplant yours. Much more likely however is that people say "yep, that
sounds reasonable" and someone like me applies it. Either way the docs end
up improved.
-- 
perl -Mre=debug -e "/just|another|perl|hacker/"

Thread Previous


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About