embed.fnc: Refactor comments about NN, NULLOK etc

This consolidates the several portions of this file that dealt with
these; making it easier to understand.

Author: khwilliamson

embed.fnc

@@ -130,6 +130,44 @@
 :         yourself, and from within it, refer to the function in its full
 :         'Perl_' form with any necessary thread context parameter.
 :
+: AUTOMATIC PARAMETER SANITY CHECKING
+:
+:   regen/embed.pl generates macros for each entry (unless excluded by the G
+:   flag) that do a bit of parameter validation.  If your element is named
+:   'foo()', the generated macro will be named 'PERL_ARGS_ASSERT_FOO'.  You
+:   should place a call to that macro before any other code in foo().  It will
+:   automatically expand to whatever checking is currently generated for foo
+:   (often none).  These are in the form of assert() calls, so only are
+:   activated for DEBUGGING builds.
+:
+:   You must specify what checking is needed for all pointer arguments.  If the
+:   pointer is allowed to point to NULL, prefix that argument with 'NULLOK'
+:   (following the template of the many entries in this file that have that).
+:   If it can't be NULL, use 'NN' (again many entries herein do that).
+:   The reason for this requirement is to tell the maintainers that you have
+:   considered the question about the argument, and this is the answer.
+:
+:   For a numeric argument, you may specify that it can't be 0 by using 'NZ'
+:
+:   regen/embed.pl may automatically add further checking for any argument as
+:   it deems desirable.  You can override this by specifying 'NOCHECK'
+:
+:	Currently this further checking is just for pointer parameters that
+:	point to AVs, CVs or HVs.  The check is that the SV being pointed to is
+:	of the intended type, by inspecting its SvTYPE(). For some functions
+:	this check may be inappropriate, as in rare cases the arguments passed
+:	may not be of the correct type. As already mentioned, NOCHECK
+:	suppresses this check.
+:
+:   Currently, it is optional to include an empty ARGS_ASSERT macro in your
+:   functions.  But a porting test enforces that a non-empty one is included.
+:   The call should be at the top of your function so that the sanity checks
+:   have passed before anything tries to use an argument.  When writing a new
+:   function, add the macro even if not required, and you'll never have to go
+:   back and add one later when more checks do get added
+:
+: AUTOMATIC DOCUMENTATION GENERATION
+:
 : Just below is a description of the relevant parts of the automatic
 : documentation generation system which heavily involves this file.  Below that
 : is a description of all the flags used in this file.
@@ -275,6 +313,8 @@
 :
 : porting/diag.t checks some things for consistency based on this file.
 :
+: FLAGS REFERENCE
+:
 : The remainder of these introductory comments detail all the possible flags:
 :
 :   'A'  Both long and short names are accessible fully everywhere (usually
@@ -388,21 +428,12 @@
 :        flag even on a format function is if the format would generate error:
 :        format string argument is not a string type
 :
-:   '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
+:   'G'  Suppress empty PERL_ARGS_ASSERT_foo macro.  Normally such a macro is
+:        generated for all entries for functions 'foo' in this file.  The macro
+:        is empty unless regen/embed.pl deems that there should be assert()
+:        calls to verify the sanity of some or all of foo's arguments.
+:
+:          proto.h: An empty PERL_ARGS_ASSERT macro is not defined
 :
 :   'h'  Hide any documentation that would normally go into perlapi or
 :        perlintern. This is typically used when the documentation is actually
@@ -623,25 +654,9 @@
 :        indicate that it does not have enough information to generate a
 :        proper test case.
 :
-: In this file, pointer parameters that must not be passed NULLs should be
-: prefixed with NN.
-:
-: And, pointer parameters that may be NULL should be prefixed with NULLOK.
-: This has no effect on output yet.  It's a notation for the maintainers to
-: know "I have defined whether NULL is OK or not" rather than having neither
-: NULL or NULLOK, which is ambiguous.
-:
-: Pointer parameters that point to AVs, CVs or HVs will generate additional
-: checks in the arguments assertion macro, that check on entry to the
-: function that the SV being pointed to is of the intended type, by
-: inspecting its SvTYPE(). For some functions this check may be inappropriate
-: as in rare cases the arguments passed may not be of the correct type. To
-: skip checking on an argument type, prefix its type with NOCHECK.
-:
-: Numeric arguments may also be prefixed with NZ, which will cause the
-: appropriate asserts to be generated to validate that this is the case.
-:
-: Flags should be sorted asciibetically.
+: regen/embed.pl will rewrite this file with the entries within each condition
+: sorted in a (somewhat-modified) dictionary order, and each entry's flags
+: sorted asciibetically.
 :
 : Please keep the next line *BLANK*