expand flag descriptions in in embed.fnc

For each flag, try to list what precise effects that flag has

1 files changed, 93 insertions, 24 deletions

diff --git a/embed.fnc b/embed.fnc
index 91bc6ee8aa..134a440c73 100644
--- a/embed.fnc
+++ b/embed.fnc
@@ -1,5 +1,7 @@
 : BEGIN {die "You meant to run embed.pl"} # Stop early if fed to perl.
 :
+: This file is processed by embed.pl and autodoc.pl
+:
 : Lines are of the form:
 :    flags|return_type|function_name|arg1|arg2|...|argN
 :
@@ -7,30 +9,97 @@
 : Leading and trailing whitespace will be ignored in each component.
 :
 : flags are single letters with following meanings:
-:	A		member of public API
-:	a		allocates memory a la malloc/calloc.  Is also "R".
-:	b		binary backward compatibility; function is a macro
-:			but has also Perl_ implementation (which is exported)
-:	D		function is deprecated
-:	d		function has documentation with its source
-:	E		visible to extensions included in the Perl core
-:	f		function takes printf style format string, varargs
-:	M		may change
-:	m		Implemented as a macro - no export, no
-:			proto, no #define
-:	n		has no implicit interpreter/thread context argument
-:	o		has no compatibility macro (#define foo Perl_foo)
-:	P		pure function: no effects except the return value;
-:			return value depends only on parms and/or globals
-:	p		function has a Perl_ prefix
-:	R		Return value must not be ignored.
-:	r		function never returns
-:	s		static function, should have an S_ prefix in
-:			source file; for macros (m), suffix the usage
-:			example with a semicolon
-:	U		suppress usage example in autogenerated documentation
-:	X		explicitly exported
-:	x		not exported
+:
+:   A  Member of public API:
+:
+:         add entry to global.sym (unless x or m);
+:         any doc entry goes in perlapi.pod rather than perlintern.api
+:         makes '#define foo Perl_foo' scope not just for PERL_CORE/PERL_EXT
+:
+:   a  Allocates memory a la malloc/calloc.  Also implies "R":
+:
+:         proto.h: add __attribute__malloc__
+:
+:   b  Binary backward compatibility; function is a macro
+:      but has also Perl_ implementation (which is exported):
+:
+:         add entry to global.sym;
+:         don't define PERL_ARGS_ASSERT_FOO
+:
+:   D  Function is deprecated:
+:
+:         proto.h: add __attribute__deprecated__
+:
+:   d  Function has documentation with its source:
+:
+:         enables 'no docs for foo" warning in autodoc.pl
+:
+:   E  Visible to extensions included in the Perl core:
+:
+:         in embed.h, change "#ifdef PERL_CORE"
+:         into               "#if defined(PERL_CORE) || defined(PERL_EXT)"
+:
+:   f  Function takes printf style format string, varargs:
+:
+:         proto.h: add __attribute__format__ (or ...null_ok__)
+:
+:   M  May change:
+:
+:         (currently no effect)
+:
+:   m  Implemented as a macro:
+:
+:         suppress proto.h entry
+:         suppress global.sym entry
+:         suppress embed.h entry
+:
+:   n  Has no implicit interpreter/thread context argument:
+:
+:         suppress the pTHX part of "foo(pTHX...)" in proto.h;
+:         In the PERL_IMPLICIT_SYS branch of embed.h, generates
+:             "#define foo Perl_foo",      rather than
+:             "#define foo(a,b,c) Perl_foo(aTHX_ a,b,c)
+:
+:   o  Has no Perl_foo compatibility macro:
+:
+:         embed.h: suppress "#define foo Perl_foo"
+:
+:   P  Pure function: no effects except the return value;
+:      return value depends only on params and/or globals:
+:
+:         proto.h: add __attribute__pure__
+:
+:   p  Function in source code has a Perl_ prefix:
+:
+:         proto.h: function is declared as Perl_foo rather than foo
+:         embed.h: "#define foo Perl_foo" entries added
+:
+:   R  Return value must not be ignored (also implied by 'a' flag):
+:
+:        proto.h: add __attribute__warn_unused_result__
+:
+:   r  Function never returns:
+:
+:        proto.h: add __attribute__noreturn__
+:
+:   s  Static function: function in source code has a S_ prefix:
+:
+:         proto.h: function is declared as S_foo rather than foo,
+:                STATIC is added to declaration;
+:         embed.h: "#define foo S_foo" entries added
+:
+:   U  Suppress usage example in autogenerated documentation
+:
+:         (currently no effect)
+:
+:   X  Explicitly exported:
+:
+:         add entry to global.sym, unless x or m
+:
+:   x  Not exported
+:
+:         suppress entry in global.sym
+:
 : (see also L<perlguts/Internal Functions> for those flags.)
 :
 : Pointer parameters that must not be passed NULLs should be prefixed with NN.