develooper Front page | perl.perl5.porters | Postings from January 2013

Re: [perl #116366] [PATCH] better POD for unpackstring

Thread Previous | Thread Next
From:
Steffen Mueller
Date:
January 14, 2013 17:24
Subject:
Re: [perl #116366] [PATCH] better POD for unpackstring
Message ID:
50F43F24.6070307@cpan.org
On 01/14/2013 01:57 PM, Dave Mitchell wrote:
> On Sat, Jan 12, 2013 at 06:08:49PM -0800, bulk88 wrote:
>> diff --git a/pp_pack.c b/pp_pack.c
>> index 50d4a63..cc1e637 100644
>> --- a/pp_pack.c
>> +++ b/pp_pack.c
>> @@ -1190,8 +1190,10 @@ first_symbol(const char *pat, const char *patend) {
>>   =for apidoc unpackstring
>>
>>   The engine implementing unpack() Perl function. C<unpackstring> puts the
>> -extracted list items on the stack and returns the number of elements.
>> +extracted list items on the @_ stack and returns the number of elements.
>>   Issue C<PUTBACK> before and C<SPAGAIN> after the call to this function.
>> +Unlike L</call_pv>, do not do a C<PUSHMARK>. This function takes no parameters
>> +on the @_ stack.
>
> I'm not very keen on this change. I've never heard the perl stack referred
> to as the '@_ stack' before. I'd suggest just calling it 'the perl stack'
> (yes, perl has several stacks, but the PL_stack_sp stack is the only one
> you would normally expect to push values onto). Or perhaps 'the argument
> stack', which is what xstut.pod does.
>
> The PUSHMARK thing I find totally confusing.  I guess you're trying to say
> that the function won't pop a mark?? In which case maybe something like:
>
>      The function does not take any values from the argument stack, nor
>      does it pop any marks.

I'd be all for "the argument stack", which is how I read "the @_ stack". 
"The perl stack" still gives me a moment of pause thinking "like perl 
had just the one!?" every time.

Sorry if I was too quick in applying this.

--Steffen

Thread Previous | Thread Next


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