embed.fnc: Update comments

embed.fnc

@@ -1,26 +1,26 @@
 : BEGIN{die "You meant to run regen/embed.pl"} # Stop early if fed to perl.
 :
-: WARNING:  The meanings of some flags have been changed as of v5.31.0
+: ALL NON-STATIC FUNCTIONS DEFINED BY PERL NEED TO BE LISTED IN THIS FILE.
 :
 : This file is known to be processed by regen/embed.pl, autodoc.pl,
 : makedef.pl, Devel::PPPort, and porting/diag.t.
 :
 : This file contains entries for various functions, macros, typedefs, and
-: arrays defined by perl.  Each entry includes the name, parameters, and
+: other values defined by perl.  Each entry includes the name, parameters, and
 : various attributes about it.  In most functions listed here, the name is a
 : short name, and the function's real name is the short one, prefixed by either
 : 'Perl_' (for publicly visible functions) or 'S_' (for internal-to-a-file
 : static ones).  In many instances a macro is defined that is the name in this
 : file, and which expands to call the real (full) name, with any appropriate
-: thread context paramaters, thus hiding that detail from the typical code.
+: thread context parameters, thus hiding that detail from the typical code.
 :
 : Many macros (as opposed to functions) listed here are the complete full name,
 : though we may want to start converting those to have full names.
 :
-: All non-static functions defined by perl need to be listed in this file.
 : embed.pl uses the entries here to construct:
 :   1) proto.h to declare to the compiler the function interfaces; and
-:   2) embed.h to create short name macros
+:   2) embed.h to create short name macros, and to control the visibility of
+:      other macros
 :
 : Static functions internal to a file need not appear here, but there is
 : benefit to declaring them here:
@@ -72,8 +72,14 @@
 : backport the fixed version to modules.  The only disadvantage khw can think
 : of is the namespace pollution one.
 :
-: WARNING: Any macro created in a header file is visible to XS code, unless
-: care is taken to wrap it within C preprocessor guards like the following
+: The default for any macro created after v5.43.6 is to hide it from all but
+: the Perl core.  Use the visibility-affecting flags described below to change
+: that.
+:
+: WARNING: The default hiding of symbols from XS code applies only to functions
+: and macros.  Other types of values that are created in a header file, such as
+: typedefs and enum names, will be visible to XS code, unless care is taken to
+: wrap them within C preprocessor guards like the following
 :
 :    #if defined(PERL_CORE)
 :    ...
@@ -92,56 +98,49 @@
 : file they are intended for, and the generated PERL_ARGS_ macros will only
 : be available to inline functions in the appropriate context.
 :
-: From time to time it may be necessary to change or expand which files can
-: see a function, therefore we prefer the '#if defined()' form of condition
-: instead of the '#ifdef' form as the latter only works with one symbol and
-: the former can be combined with more than one.  It is also why you may see
-: functions with an 's' or 'i' export type grouped together into a single
-: conditional block separate from most of the other functions from the same
-: file with 'p' in them.
-:
-: The 'A' flag is used to make a function and its short name visible everywhere
-:         on all platforms.  This should be used to make it part of Perl's API
-:         contract with XS developers.  The documentation for these is usually
-:         placed in perlapi.  If no documentation exists, that fact is also
-:         noted in perlapi.
+: The 'A' flag is used to make an element visible everywhere on all platforms.
+:	  This flag should be used to make it part of Perl's API contract with
+:	  XS developers.  The documentation for these is usually placed in
+:	  perlapi.  If no documentation exists, that fact is also noted in
+:	  perlapi.
 :
-:         These require one of the /[iIpS]/ flags to give callers a name to use
-:         that won't possibly collide with their own
+:         Functions require one of the /[iIpS]/ flags to give callers a name to
+:         use that won't possibly collide with their own
 :
-: The 'C' flag is used instead for functions and their short names that need to
-:         be accessible everywhere, typically because they are called from a
-:         publicly available macro or inline function, but they are not for
-:         public use by themselves.  The documentation for these is placed in
-:         perlintern.  If no documentation exists, that fact is also noted in
-:         perlintern.
+: The 'C' flag is used instead for elements that need to be accessible
+:	  everywhere, typically because they are called from a publicly
+:	  available macro or inline function, but they are not for public use
+:	  by themselves.  The documentation for these is placed in perlintern.
+:	  If no documentation exists, that fact is also noted in perlintern.
 :
-:	  Use the 'X' flag instead to suppress the short name outside the core
+:	  Use the 'X' flag instead to suppress the short name for functions
+:	  outside the core
 :
-:         These require one of the /[iIpS]/ flags to give callers a name to use
-:         that won't possibly collide with their own
+:         Functions require one of the /[iIpS]/ flags to give callers a name to
+:         use that won't possibly collide with their own
 :
 :         Some of these have been constructed so that the wrapper macro names
 :         begin with an underscore to lessen the chances of a name collision.
 :         However, this is contrary to the C standard, and those should be
 :         changed.
 :
-: The 'E' flag is used instead for a function and its short name that is
-:         supposed to be used only in the core plus extensions compiled with
-:         the PERL_EXT symbol defined.  Again, on some platforms, the function
-:         will be visible everywhere, so one of the /[iIpS]/ flags are
-:         generally needed.  Also note that an XS writer can always cheat and
-:         pretend to be an extension by #defining PERL_EXT.
-:
-: The 'X' flag is similar to the 'C' flag in that the function (whose entry
-:         better have the 'p' flag) is accessible everywhere on all platforms.
-:         However the short name macro that normally gets generated is
-:         suppressed outside the core.  (Except it is also visible in PERL_EXT
-:         extensions if the 'E' flag is also specified.)  This flag is used for
-:         functions that are called from a public macro, the name of which
-:         isn't derived from the function name.  You'll have to write the macro
-:         yourself, and from within it, refer to the function in its full
-:         'Perl_' form with any necessary thread context parameter.
+: The 'E' flag is used instead for elements that are supposed to be used only
+:	  in the core, plus extensions compiled with the PERL_EXT symbol
+:	  defined.  Again, on some platforms, functions marked with this will
+:	  be visible everywhere, so one of the /[iIpS]/ flags is generally
+:	  needed.  Also note that an XS writer can always cheat and pretend to
+:	  be an extension by #defining PERL_EXT.
+:
+: The 'X' flag applies only to functions.  It is similar to the 'C' flag in
+:	  that the function (whose entry better have the 'p' flag) is
+:	  accessible everywhere on all platforms.  However the short name macro
+:	  that normally gets generated is suppressed outside the core.  (Except
+:	  it is also visible in PERL_EXT extensions if the 'E' flag is also
+:	  specified.)  This flag is used for functions that are called from a
+:	  public macro, the name of which isn't derived from the function name.
+:	  You'll have to write the macro yourself, and from within it, refer to
+:	  the function in its full 'Perl_' form with any necessary thread
+:	  context parameter.
 :
 : AUTOMATIC SORTING and FORMATTING of this file
 :
@@ -423,15 +422,15 @@
 : The remainder of these introductory comments detail all the possible flags:
 :
 :   'A'  Both long and short names are accessible fully everywhere (usually
-:        part of the public API). Requires one of /[iIpS]/ flags.  If the
-:	 function is not part of the public API, instead use 'C', 'E', or 'X'.
+:        part of the public API).  If this element is a function, this requires
+:        one of /[iIpS]/ flags.  If the element is not part of the public API,
+:        instead use 'C', 'E', or 'X'.
 :
 :        * adds entry to the list of symbols available on all platforms unless
 :          'e' or 'm' are also specified;
 :        * any doc entry goes in perlapi.pod rather than perlintern.pod. If
 :          there isn't a doc entry, autodoc.pl lists this in perlapi as
-:          existing and being undocumented; unless 'x' is also specified, in
-:          which case it simply isn't listed.
+:          existing and being undocumented.
 :        * makes the short name defined for everywhere, not just for PERL_CORE
 :          or PERL_EXT
 :
@@ -475,32 +474,33 @@
 :        * create PERL_ARGS_ASSERT_foo;
 :        * add embed.h entry (unless overridden by the 'M' or 'o' flags)
 :
-:   'C'  Intended for core use only. This indicates to XS writers that they
-:        shouldn't be using this function. Devel::PPPort informs them of this,
-:        for example. Some functions have to be accessible everywhere even if
-:        they are not intended for public use. An example is helper functions
-:        that are called from inline ones that are publicly available.
-:        Requires one of /[iIpS]/ flags.
+:   'C'  Intended for core use only.  XS writers may not even know they exist,
+:	 since they don't get documented in perlapi.  But should they try
+:	 to use them anyway, Devel::PPPort informs them that this is a mistake.
+:	 Some functions have to be accessible everywhere even if they are not
+:	 intended for public use. An example is helper functions that are
+:	 called from inline ones that are publicly available.  Requires one of
+:	 the /[iIpS]/ flags if the element is a function.
 :
 :        * add entry to the list of symbols available on all platforms unless e
 :          or m are also specified;
 :        * any doc entry goes in perlintern.pod rather than perlapi.pod. If
 :          there isn't a doc entry, autodoc.pl lists this in perlintern as
 :          existing and being undocumented
-:        * makes the short name defined for everywhere, not just for PERL_CORE
-:          or PERL_EXT
+:        * makes the function's short name defined for everywhere, not just for
+:	   PERL_CORE or PERL_EXT
 :
-:   'D'  Function is deprecated.
+:   'D'  The element is deprecated.
 :
-:	(Add a comment to the function source when adding this flag indicating
-:	what release it is first being deprecated in.  This will prevent having
-:	to dig up this information when deciding if enough releases have passed
-:	to actually remove the function.)
+:	(You should add a comment to the source when adding this flag
+:	indicating what release it is first being deprecated in.  This will
+:	prevent having to dig up this information when deciding if enough
+:	releases have passed to actually remove it.)
 :
 :        proto.h: add __attribute__deprecated__
 :        autodoc.pl adds a note to this effect in the doc entry
 :
-:   'd'  Function has documentation (somewhere) in the source:
+:   'd'  Element has documentation (somewhere) in the source:
 :
 :        Enables 'no docs for foo" warning in autodoc.pl if the documentation
 :        isn't found.
@@ -584,11 +584,20 @@
 :        instead you define the macro as 'PERL_FOO' (all uppercase), the
 :        embed.h entry will use all uppercase.
 :
+:	 The default visibility of macros created before 5.43.7 is visible
+:	 everywhere, so the visibility flags are ignored.  Starting in that
+:	 release, the default visibility of newly created macros is core-only,
+:	 so the visibility flags do have effect.  To cause a pre-5.43.7 symbol
+:	 to be affected by a visibility flag, remove the symbol from its
+:	 override list in regen/embed.pl.
+:
 :         suppress proto.h entry (actually, not suppressed, but commented out)
 :         suppress entry in the list of exported symbols available on all
 :             platforms
 :         suppress embed.h entry (when no 'p' flag), as the implementation
 :             should furnish the macro
+:	  #undef this symbol in embed.h as needed to match the specified
+:	  visibility.
 :
 :   'M'  The implementation is furnishing its own macro instead of relying on
 :        the automatically generated short name macro (which simply expands to
@@ -732,13 +741,15 @@
 :
 :   'x'  Experimental, may change:
 :
-:          Any doc entry is marked that it may change. An undocumented
-:          experimental function is listed in perlintern rather than perlapi,
-:          even if it is allegedly API.
+:          Any doc entry is marked that this element may change.
 :
-:   'y'  Typedef.  The element names a type rather than being a macro
+:   'y'  Typedef.  The element names a type rather than being a function or
+:	 macro.  These are always visible to XS code unless guarded by
+:	 preprocessor directives,
 :
 :   '@'  The element names an array rather than being a macro or function.
+:	 These are always visible to XS code unless guarded by preprocessor
+:	 directives,
 :
 :          autodoc.pl automatically suppresses any usage information.
 :