From: Father Chrysostomos <sprout@cpan.org>
Date: Tue, 4 Dec 2012 18:48:36 +0000 (-0800)
Subject: embed.fnc: Explain how X is used for public macros
X-Git-Tag: upstream/5.20.0~4612
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=569ba91fcdabdc53eb4284f860a25273bd7fe4e1;p=platform%2Fupstream%2Fperl.git

embed.fnc: Explain how X is used for public macros

I don’t know whether my message to the list
(<20121204012335.29409.qmail@lists-nntp.develooper.com>) was noticed.

In any case, here it is for posterity.  Hopefully this will save
others from finding this out the hard way as I had to (making mistakes
and having others come and correct them).
---

diff --git a/embed.fnc b/embed.fnc
index 4e3d825..e7ac5f1 100644
--- a/embed.fnc
+++ b/embed.fnc
@@ -16,6 +16,9 @@
 :         any doc entry goes in perlapi.pod rather than perlintern.pod
 :         makes '#define foo Perl_foo' scope not just for PERL_CORE/PERL_EXT
 :
+:      If the function is only exported for use in a public
+:      macro, see X.
+:
 :   a  Allocates memory a la malloc/calloc.  Also implies "R":
 :
 :         proto.h: add __attribute__malloc__
@@ -111,6 +114,10 @@
 :
 :         add entry to the list of exported symbols, unless x or m
 :
+:      This is often used for private functions that are used by public
+:      macros.  In those cases the macros must use the long form of the
+:      name (Perl_blah(aTHX_ ...)).
+:
 :   x  Not exported
 :
 :         suppress entry in the list of exported symbols