From d412580b5bb56707bd663eed7c3e2147b4261de9 Mon Sep 17 00:00:00 2001 From: David Mitchell Date: Sun, 7 Feb 2010 20:12:18 +0000 Subject: [PATCH] expand flag descriptions in in embed.fnc For each flag, try to list what precise effects that flag has --- embed.fnc | 117 +++++++++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 93 insertions(+), 24 deletions(-) diff --git a/embed.fnc b/embed.fnc index 91bc6ee..134a440 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 for those flags.) : : Pointer parameters that must not be passed NULLs should be prefixed with NN. -- 2.7.4