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

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

Thread Previous
From:
bulk88 via RT
Date:
January 18, 2013 17:53
Subject:
[perl #116366] [PATCH] better POD for unpackstring
Message ID:
rt-3.6.HEAD-4370-1358531578-700.116366-15-0@perl.org
On Fri Jan 18 03:46:24 2013, davem wrote:
> On Mon, Jan 14, 2013 at 11:22:45AM -0800, bulk88 via RT wrote:
> [ stuff ]
> 
> Ok how about the following instead:
> 
> /*
> =for apidoc unpackstring
> 
> The engine implementing the unpack() Perl function.
> 
> Using the template pat..patend, this function unpacks the string
> s..strend into a number of mortal SVs, which it pushes onto the perl
> argument (@_) stack (so you will need to issue a C<PUTBACK> before and
> C<SPAGAIN> after the call to this function). It returns the number of
> pushed elements.
> 
> The strend and patend pointers should point to the byte following the last
> character of each string.
> 
> Although this function returns its values on the perl argument stack, it
> doesn't take any parameters from that stack (and thus in particular
> there's no need to do a PUSHMARK before calling it, unlike L</call_pv> for
> example).
> 
> =cut */
> 
> (With the above, the flags arg is still undocumented)
> 

Currently is 
__________________________________________________________________
=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.
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.

=cut */
___________________________________________________________________

davem version is better than my/current version. My nitpicking says
someone will think from reading unpackstring's docs that a call_pv
without args requires no PUSHMARK, but I think they are reading too
deeply if they think that since the first example in perlcall is a no
args call_pv that has a PUSHMARK. davem's version I think should be applied.

I asked about documenting unpackstring's flags param before but no
interest/responses
http://www.nntp.perl.org/group/perl.perl5.porters/2012/06/msg187583.html
. This ticket is not about the flags param so let us leave that out of
this ticket.
-- 
bulk88 ~ bulk88 at hotmail.com

---
via perlbug:  queue: perl5 status: resolved
https://rt.perl.org:443/rt3/Ticket/Display.html?id=116366

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