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 (file)
--- 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