Perl_foo vs. foo perl API in documentation

Finally I had a chance to read the whole new perldelta for 5.8.1. This para is 
not so clear to me:

<perldelta>
Certain Perl core C APIs like C<Perl_list> are no longer available
without their C<Perl_> prefix.  If your XS module stops working
because some functions cannot be found, in many cases a simple fix is
to add the C<Perl_> prefix to the function and the thread context
C<aTHX_> as the first argument of the function call.  This is also how
it should always have been done: letting the Perl_-less forms to leak
from the core was an accident.  For cleaner embedding you can also
force this for all APIs by defining at compile time the cpp define
PERL_NO_SHORT_NAMES.
</perldelta>

But anybody who wants to use perl API has to read perlapi.pod, which doesn't 
use the Perl_ prefix in most cases. And sometimes it's inconsistent, e.g. for 
Perl_form the entry mixes the two:

       form    Takes a sprintf-style format pattern and conventional (non-SV)
                arguments and returns the formatted string.

                    (char *) Perl_form(pTHX_ const char* pat, ...)

I'm sure that other pods use a lot of short forms as well.

So it's not surprising that non-core developers are using the short form in 
their XS/embedding code. IMHO, it's not not leaked from the core, it's 
"endorsed" by perl's own documentation. Unless I miss something obvious here.


__________________________________________________________________
Stas Bekman            JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/     mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org   http://ticketmaster.com

• Perl_foo vs. foo perl API in documentation by Stas Bekman
• Re: Perl_foo vs. foo perl API in documentation by Gurusamy Sarathy
• Re: Perl_foo vs. foo perl API in documentation by Stas Bekman