-: i Static inline: function in source code has a S_ prefix:
-:
-: proto.h: function is declared as S_foo rather than foo unless the 'p'
-: flag is also given in which case 'Perl_foo' is used,
-: PERL_STATIC_INLINE is added to the declaration
-: embed.h: "#define foo S_foo" or Perl_foo entries added
-:
-: M There is an extra macro that bypasses this function
-:
-: (requires 'p', and implies 'o') The function exists so that callers who
-: used the 'Perl_' form can continue to do so, but there is a macro
-: available without the 'Perl_' prefix that bypasses the function call,
-: such as when the function has been reduced to a wrapper around another
-: one.
-:
-: m Implemented as a macro:
-:
-: suppress proto.h entry unless 'b' also specified (actually, not
-: suppressed, but commented out)
-: suppress entry in the list of exported symbols
-: suppress embed.h entry
+: G Suppress empty PERL_ARGS_ASSERT_foo macro. Normally such a macro is
+: generated for all entries for functions 'foo' in this file. If there is
+: a pointer argument to 'foo', it needs to be declared in this file as
+: either NN or NULLOK, and the function definition must call its
+: corresponding PERL_ARGS_ASSERT_foo macro (a porting test ensures this)
+: which asserts at runtime (under DEBUGGING builds) that NN arguments are
+: not NULL. If there aren't NN arguments, use of this macro is optional.
+: Rarely, a function will define its own PERL_ARGS_ASSERT_foo macro, and
+: in those cases, adding this flag to its entry in this file will suppress
+: the normal one. It is not possible to suppress the generated macro if
+: it isn't optional, that is, if there is at least one NN argument.
+:
+: proto.h: PERL_ARGS_ASSERT macro is not defined unless the function
+: has NN arguments
+:
+: h Hide any documentation. This is used when the documentation is atypical
+: of the rest of perlapi and perlintern. In other words the item is
+: documented, but just not the standard way. One reason would be if there
+: are a bunch of macros which follow a common paradigm in their naming, so
+: rather than having an entry for each slight variation, there is an
+: overarchinge one. It is also used when the documentation is in another
+: pod, such as perlguts or warnings.h. This flag is useful for downstream
+: programs, such as Devel::PPPort.
+:
+: i inline static. This is used for functions that the compiler is being
+: requested to inline. If the function is in a header file its
+: definition will be visible (unless guarded by #if..#endif) to all
+: XS code. (A typical guard will be that it is being included in a
+: particular C file(s) or in the perl core.) Therefore, all
+: non-guarded function should also have the 'p' flag specified to avoid
+: polluting the XS code name space. Otherwise an error is generated if
+: the 'S' flag is not also specified.
+:
+: proto.h: function is declared as PERL_STATIC_INLINE
+:
+: m Implemented as a macro; there is no function associated with this name,
+: and hence no long Perl_ or S_ name. However, if the macro name itself
+: begins with 'Perl_', autodoc.pl will show a thread context parameter
+: unless the 'T' flag is specified.
+:
+: 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, as the implementation should furnish the macro
+:
+: M The implementation is furnishing its own macro instead of relying on the
+: default short name macro that simply expands to call the real name
+: function. This is used if the parameters need to be cast from what the
+: caller has, or if there is a macro that bypasses this function (whose
+: long name is being retained for backward compatibility for those who
+: call it with that name). An example is when a new function is created
+: with an extra parameter and a wrapper macro is added that has the old
+: API, but calls the new one with the exta parameter set to a default.
+:
+: This flag requires the 'p' flag to be specified, as there would be no
+: need to do this if the function weren't publicly accessible before.
+:
+: The entry is processed based on the other flags, but the:
+: embed.h entry is suppressed