Fix apidoc macro entries

This makes various fixes to the text that is used to generate the
documentation.  The dominant change is to add the 'n' flag to indicate
that the macro takes no arguments.  A couple should have been marked
with a D (for deprecated) flag, and a couple were missing parameters,
and a couple were missing return values.

These were spotted by using Devel::PPPort on them.

13 files changed, 58 insertions, 58 deletions

diff --git a/XSUB.h b/XSUB.h
index 7c0aebd2b6..1a497c2788 100644
--- a/XSUB.h
+++ b/XSUB.h
@@ -47,7 +47,7 @@ XSUB's aliases was used to invoke it.  See L<perlxs/"The ALIAS: Keyword">.
 =for apidoc Am|SV*|ST|int ix
 Used to access elements on the XSUB's stack.
 
-=for apidoc AmU||XS
+=for apidoc AmnU||XS
 Macro to declare an XSUB and its C parameter list.  This is handled by
 C<xsubpp>.  It is the same as using the more explicit C<XS_EXTERNAL> macro.
 
@@ -56,7 +56,7 @@ Macro to declare an XSUB and its C parameter list without exporting the symbols.
 This is handled by C<xsubpp> and generally preferable over exporting the XSUB
 symbols unnecessarily.
 
-=for apidoc AmU||XS_EXTERNAL
+=for apidoc AmnU||XS_EXTERNAL
 Macro to declare an XSUB and its C parameter list explicitly exporting the symbols.
 
 =for apidoc Amns||dAX
@@ -85,7 +85,7 @@ Sets up any variable needed by the C<UNDERBAR> macro.  It used to define
 C<padoff_du>, but it is currently a noop.  However, it is strongly advised
 to still use it for ensuring past and future compatibility.
 
-=for apidoc AmU||UNDERBAR
+=for apidoc AmnU||UNDERBAR
 The SV* corresponding to the C<$_> variable.  Works even if there
 is a lexical C<$_> in scope.
 
@@ -263,7 +263,7 @@ Return an empty list from an XSUB immediately.
 Used by C<xsubpp> to hook up XSUBs as Perl subs.  Adds Perl prototypes to
 the subs.
 
-=for apidoc AmU||XS_VERSION
+=for apidoc AmnU||XS_VERSION
 The version identifier for an XS module.  This is usually
 handled automatically by C<ExtUtils::MakeMaker>.  See
 C<L</XS_VERSION_BOOTCHECK>>.
@@ -283,13 +283,13 @@ matches the api version of the perl interpreter it's being loaded into.
 Set up necessary local variables for exception handling.
 See L<perlguts/"Exception Handling">.
 
-=for apidoc AmU||XCPT_TRY_START
+=for apidoc AmnU||XCPT_TRY_START
 Starts a try block.  See L<perlguts/"Exception Handling">.
 
-=for apidoc AmU||XCPT_TRY_END
+=for apidoc AmnU||XCPT_TRY_END
 Ends a try block.  See L<perlguts/"Exception Handling">.
 
-=for apidoc AmU||XCPT_CATCH
+=for apidoc AmnU||XCPT_CATCH
 Introduces a catch block.  See L<perlguts/"Exception Handling">.
 
 =for apidoc Amns||XCPT_RETHROW
diff --git a/av.h b/av.h
index 7cb63b484c..72267d6202 100644
--- a/av.h
+++ b/av.h
@@ -39,7 +39,7 @@ struct xpvav {
 /*
 =head1 Handy Values
 
-=for apidoc AmU||Nullav
+=for apidoc ADmnU||Nullav
 Null AV pointer.
 
 (deprecated - use C<(AV *)NULL> instead)
diff --git a/cop.h b/cop.h
index fca2aa755c..b9b61faa76 100644
--- a/cop.h
+++ b/cop.h
@@ -922,27 +922,27 @@ struct context {
 */
 
 /*
-=for apidoc AmU||G_SCALAR
+=for apidoc AmnU||G_SCALAR
 Used to indicate scalar context.  See C<L</GIMME_V>>, C<L</GIMME>>, and
 L<perlcall>.
 
-=for apidoc AmU||G_ARRAY
+=for apidoc AmnU||G_ARRAY
 Used to indicate list context.  See C<L</GIMME_V>>, C<L</GIMME>> and
 L<perlcall>.
 
-=for apidoc AmU||G_VOID
+=for apidoc AmnU||G_VOID
 Used to indicate void context.  See C<L</GIMME_V>> and L<perlcall>.
 
-=for apidoc AmU||G_DISCARD
+=for apidoc AmnU||G_DISCARD
 Indicates that arguments returned from a callback should be discarded.  See
 L<perlcall>.
 
-=for apidoc AmU||G_EVAL
+=for apidoc AmnU||G_EVAL
 
 Used to force a Perl C<eval> wrapper around a callback.  See
 L<perlcall>.
 
-=for apidoc AmU||G_NOARGS
+=for apidoc AmnU||G_NOARGS
 
 Indicates that no arguments are being sent to a callback.  See
 L<perlcall>.
@@ -1101,7 +1101,7 @@ typedef struct stackinfo PERL_SI;
 =for apidoc Amns||dMULTICALL
 Declare local variables for a multicall.  See L<perlcall/LIGHTWEIGHT CALLBACKS>.
 
-=for apidoc Amns||PUSH_MULTICALL
+=for apidoc Ams||PUSH_MULTICALL|CV* the_cv
 Opening bracket for a lightweight callback.
 See L<perlcall/LIGHTWEIGHT CALLBACKS>.
 
diff --git a/cv.h b/cv.h
index d50e320f16..35751eb4dd 100644
--- a/cv.h
+++ b/cv.h
@@ -18,7 +18,7 @@ struct xpvcv {
 /*
 =head1 Handy Values
 
-=for apidoc AmU||Nullcv
+=for apidoc ADmnU||Nullcv
 Null CV pointer.
 
 (deprecated - use C<(CV *)NULL> instead)
diff --git a/handy.h b/handy.h
index 51f79efcf3..c4363835b3 100644
--- a/handy.h
+++ b/handy.h
@@ -20,11 +20,11 @@
 /*
 =head1 Handy Values
 
-=for apidoc AmU||Nullch
+=for apidoc AmnU||Nullch
 Null character pointer.  (No longer available when C<PERL_CORE> is
 defined.)
 
-=for apidoc AmU||Nullsv
+=for apidoc AmnU||Nullsv
 Null SV pointer.  (No longer available when C<PERL_CORE> is defined.)
 
 =cut
@@ -317,7 +317,7 @@ string/length pair.
 Like C<sv_setpvn_mg>, but takes a literal string instead of a
 string/length pair.
 
-=for apidoc Am|SV *|sv_setref_pvs|"literal string" s
+=for apidoc Am|SV *|sv_setref_pvs|SV *const rv|const char *const classname|"literal string" s
 Like C<sv_setref_pvn>, but takes a literal string instead of
 a string/length pair.
 
diff --git a/hv.h b/hv.h
index dcc6eb1e2f..96a710f1a7 100644
--- a/hv.h
+++ b/hv.h
@@ -142,14 +142,14 @@ struct xpvhv {
 /*
 =head1 Hash Manipulation Functions
 
-=for apidoc AmU||HEf_SVKEY
+=for apidoc AmnU||HEf_SVKEY
 This flag, used in the length slot of hash entries and magic structures,
 specifies the structure contains an C<SV*> pointer where a C<char*> pointer
 is to be expected.  (For information only--not to be used).
 
 =head1 Handy Values
 
-=for apidoc AmU||Nullhv
+=for apidoc ADmnU||Nullhv
 Null HV pointer.
 
 (deprecated - use C<(HV *)NULL> instead)
diff --git a/pad.c b/pad.c
index 7d54172658..c0098bedf3 100644
--- a/pad.c
+++ b/pad.c
@@ -121,12 +121,12 @@ to be generated in evals, such as
 For state vars, C<SVs_PADSTALE> is overloaded to mean 'not yet initialised',
 but this internal state is stored in a separate pad entry.
 
-=for apidoc AmxU|PADNAMELIST *|PL_comppad_name
+=for apidoc AmnxU|PADNAMELIST *|PL_comppad_name
 
 During compilation, this points to the array containing the names part
 of the pad for the currently-compiling code.
 
-=for apidoc AmxU|PAD *|PL_comppad
+=for apidoc AmnxU|PAD *|PL_comppad
 
 During compilation, this points to the array containing the values
 part of the pad for the currently-compiling code.  (At runtime a CV may
@@ -134,7 +134,7 @@ have many such value arrays; at compile time just one is constructed.)
 At runtime, this points to the array containing the currently-relevant
 values for the pad for the currently-executing code.
 
-=for apidoc AmxU|SV **|PL_curpad
+=for apidoc AmnxU|SV **|PL_curpad
 
 Points directly to the body of the L</PL_comppad> array.
 (I.e., this is C<PadARRAY(PL_comppad)>.)
diff --git a/perlvars.h b/perlvars.h
index 466c515ebb..df5b2f8c64 100644
--- a/perlvars.h
+++ b/perlvars.h
@@ -114,7 +114,7 @@ PERLVAR(G, C_locale_obj, locale_t)
 PERLVARI(G, watch_pvx,	char *, NULL)
 
 /*
-=for apidoc AmU|Perl_check_t *|PL_check
+=for apidoc AmnU|Perl_check_t *|PL_check
 
 Array, indexed by opcode, of functions that will be called for the "check"
 phase of optree building during compilation of Perl code.  For most (but
@@ -176,7 +176,7 @@ PERLVARI(G, my_cxt_index, int,	0)
 PERLVARI(G, veto_cleanup, int, FALSE)	/* exit without cleanup */
 
 /*
-=for apidoc AmUx|Perl_keyword_plugin_t|PL_keyword_plugin
+=for apidoc AmnUx|Perl_keyword_plugin_t|PL_keyword_plugin
 
 Function pointer, pointing at a function used to handle extended keywords.
 The function should be declared as
diff --git a/pp.h b/pp.h
index 54a19edba1..d4176db9ed 100644
--- a/pp.h
+++ b/pp.h
@@ -13,11 +13,11 @@
 /*
 =head1 Stack Manipulation Macros
 
-=for apidoc AmU||SP
+=for apidoc AmnU||SP
 Stack pointer.  This is usually handled by C<xsubpp>.  See C<L</dSP>> and
 C<SPAGAIN>.
 
-=for apidoc AmU||MARK
+=for apidoc AmnU||MARK
 Stack marker variable for the XSUB.  See C<L</dMARK>>.
 
 =for apidoc Am|void|PUSHMARK|SP
@@ -42,7 +42,7 @@ C<L</dORIGMARK>>.
 =for apidoc Amns||dORIGMARK
 Saves the original stack mark for the XSUB.  See C<L</ORIGMARK>>.
 
-=for apidoc AmU||ORIGMARK
+=for apidoc AmnU||ORIGMARK
 The original stack mark for the XSUB.  See C<L</dORIGMARK>>.
 
 =for apidoc Amns||SPAGAIN
@@ -243,7 +243,7 @@ Push an SV onto the stack and mortalizes the SV.  The stack must have room
 for this element.  Does not use C<TARG>.  See also C<L</PUSHs>> and
 C<L</mXPUSHs>>.
 
-=for apidoc Am|void|PUSHmortal
+=for apidoc Amn|void|PUSHmortal
 Push a new mortal SV onto the stack.  The stack must have room for this
 element.  Does not use C<TARG>.  See also C<L</PUSHs>>, C<L</XPUSHmortal>> and
 C<L</XPUSHs>>.
@@ -270,7 +270,7 @@ C<L</XPUSHu>>.
 Push an SV onto the stack, extending the stack if necessary and mortalizes
 the SV.  Does not use C<TARG>.  See also C<L</XPUSHs>> and C<L</mPUSHs>>.
 
-=for apidoc Am|void|XPUSHmortal
+=for apidoc Amn|void|XPUSHmortal
 Push a new mortal SV onto the stack, extending the stack if necessary.
 Does not use C<TARG>.  See also C<L</XPUSHs>>, C<L</PUSHmortal>> and
 C<L</PUSHs>>.
@@ -638,7 +638,7 @@ Does not use C<TARG>.  See also C<L</XPUSHu>>, C<L</mPUSHu>> and C<L</PUSHu>>.
 #define opASSIGN (PL_op->op_flags & OPf_STACKED)
 
 /*
-=for apidoc mU||LVRET
+=for apidoc mnU||LVRET
 True if this op will be the return value of an lvalue subroutine
 
 =cut */
diff --git a/regen/unicode_constants.pl b/regen/unicode_constants.pl
index c3fa70a6e6..b2c8c360c7 100644
--- a/regen/unicode_constants.pl
+++ b/regen/unicode_constants.pl
@@ -31,7 +31,7 @@ print $out_fh <<END;
 /*
 =head1 Unicode Support
 
-=for apidoc AmU|placeholder|BOM_UTF8
+=for apidoc AmnU|const char *|BOM_UTF8
 
 This is a macro that evaluates to a string constant of the  UTF-8 bytes that
 define the Unicode BYTE ORDER MARK (U+FEFF) for the platform that perl
@@ -40,7 +40,7 @@ works on both ASCII and EBCDIC platforms.
 S<C<sizeof(BOM_UTF8) - 1>> can be used to get its length in
 bytes.
 
-=for apidoc AmU|placeholder|REPLACEMENT_CHARACTER_UTF8
+=for apidoc AmnU|const char *|REPLACEMENT_CHARACTER_UTF8
 
 This is a macro that evaluates to a string constant of the  UTF-8 bytes that
 define the Unicode REPLACEMENT CHARACTER (U+FFFD) for the platform that perl
diff --git a/sv.h b/sv.h
index 15adf03449..24c728dcd2 100644
--- a/sv.h
+++ b/sv.h
@@ -15,7 +15,7 @@
 /*
 =head1 SV Flags
 
-=for apidoc AmU||svtype
+=for apidoc AmnU||svtype
 An enum of flags for Perl types.  These are found in the file F<sv.h>
 in the C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
 
@@ -72,52 +72,52 @@ hold C<undef> or a string.  C<SVt_PVIV> is a superset of C<SVt_PV> and C<SVt_IV>
 C<SVt_PVNV> is similar.  C<SVt_PVMG> can hold anything C<SVt_PVNV> can hold, but it
 can, but does not have to, be blessed or magical.
 
-=for apidoc AmU||SVt_NULL
+=for apidoc AmnU||SVt_NULL
 Type flag for scalars.  See L</svtype>.
 
-=for apidoc AmU||SVt_IV
+=for apidoc AmnU||SVt_IV
 Type flag for scalars.  See L</svtype>.
 
-=for apidoc AmU||SVt_NV
+=for apidoc AmnU||SVt_NV
 Type flag for scalars.  See L</svtype>.
 
-=for apidoc AmU||SVt_PV
+=for apidoc AmnU||SVt_PV
 Type flag for scalars.  See L</svtype>.
 
-=for apidoc AmU||SVt_PVIV
+=for apidoc AmnU||SVt_PVIV
 Type flag for scalars.  See L</svtype>.
 
-=for apidoc AmU||SVt_PVNV
+=for apidoc AmnU||SVt_PVNV
 Type flag for scalars.  See L</svtype>.
 
-=for apidoc AmU||SVt_PVMG
+=for apidoc AmnU||SVt_PVMG
 Type flag for scalars.  See L</svtype>.
 
-=for apidoc AmU||SVt_INVLIST
+=for apidoc AmnU||SVt_INVLIST
 Type flag for scalars.  See L</svtype>.
 
-=for apidoc AmU||SVt_REGEXP
+=for apidoc AmnU||SVt_REGEXP
 Type flag for regular expressions.  See L</svtype>.
 
-=for apidoc AmU||SVt_PVGV
+=for apidoc AmnU||SVt_PVGV
 Type flag for typeglobs.  See L</svtype>.
 
-=for apidoc AmU||SVt_PVLV
+=for apidoc AmnU||SVt_PVLV
 Type flag for scalars.  See L</svtype>.
 
-=for apidoc AmU||SVt_PVAV
+=for apidoc AmnU||SVt_PVAV
 Type flag for arrays.  See L</svtype>.
 
-=for apidoc AmU||SVt_PVHV
+=for apidoc AmnU||SVt_PVHV
 Type flag for hashes.  See L</svtype>.
 
-=for apidoc AmU||SVt_PVCV
+=for apidoc AmnU||SVt_PVCV
 Type flag for subroutines.  See L</svtype>.
 
-=for apidoc AmU||SVt_PVFM
+=for apidoc AmnU||SVt_PVFM
 Type flag for formats.  See L</svtype>.
 
-=for apidoc AmU||SVt_PVIO
+=for apidoc AmnU||SVt_PVIO
 Type flag for I/O objects.  See L</svtype>.
 
 =cut
diff --git a/toke.c b/toke.c
index 694b008761..e21a95fcd5 100644
--- a/toke.c
+++ b/toke.c
@@ -25,7 +25,7 @@
 =head1 Lexer interface
 This is the lower layer of the Perl parser, managing characters and tokens.
 
-=for apidoc AmU|yy_parser *|PL_parser
+=for apidoc AmnU|yy_parser *|PL_parser
 
 Pointer to a structure encapsulating the state of the parsing operation
 currently in progress.  The pointer can be locally changed to perform
@@ -833,7 +833,7 @@ Perl_parser_free_nexttoke_ops(pTHX_  yy_parser *parser, OPSLAB *slab)
 
 
 /*
-=for apidoc AmxUN|SV *|PL_parser-E<gt>linestr
+=for apidoc AmnxUN|SV *|PL_parser-E<gt>linestr
 
 Buffer scalar containing the chunk currently under consideration of the
 text currently being lexed.  This is always a plain string scalar (for
@@ -860,7 +860,7 @@ lexing position is pointed to by L</PL_parser-E<gt>bufptr>.  Direct use
 of these pointers is usually preferable to examination of the scalar
 through normal scalar means.
 
-=for apidoc AmxUN|char *|PL_parser-E<gt>bufend
+=for apidoc AmnxUN|char *|PL_parser-E<gt>bufend
 
 Direct pointer to the end of the chunk of text currently being lexed, the
 end of the lexer buffer.  This is equal to C<SvPVX(PL_parser-E<gt>linestr)
@@ -868,7 +868,7 @@ end of the lexer buffer.  This is equal to C<SvPVX(PL_parser-E<gt>linestr)
 always located at the end of the buffer, and does not count as part of
 the buffer's contents.
 
-=for apidoc AmxUN|char *|PL_parser-E<gt>bufptr
+=for apidoc AmnxUN|char *|PL_parser-E<gt>bufptr
 
 Points to the current position of lexing inside the lexer buffer.
 Characters around this point may be freely examined, within
@@ -886,7 +886,7 @@ Interpretation of the buffer's octets can be abstracted out by
 using the slightly higher-level functions L</lex_peek_unichar> and
 L</lex_read_unichar>.
 
-=for apidoc AmxUN|char *|PL_parser-E<gt>linestart
+=for apidoc AmnxUN|char *|PL_parser-E<gt>linestart
 
 Points to the start of the current line inside the lexer buffer.
 This is useful for indicating at which column an error occurred, and
diff --git a/unicode_constants.h b/unicode_constants.h
index d7ccd90b7e..4102f4b915 100644
--- a/unicode_constants.h
+++ b/unicode_constants.h
@@ -24,7 +24,7 @@
 /*
 =head1 Unicode Support
 
-=for apidoc AmU|placeholder|BOM_UTF8
+=for apidoc AmnU|const char *|BOM_UTF8
 
 This is a macro that evaluates to a string constant of the  UTF-8 bytes that
 define the Unicode BYTE ORDER MARK (U+FEFF) for the platform that perl
@@ -33,7 +33,7 @@ works on both ASCII and EBCDIC platforms.
 S<C<sizeof(BOM_UTF8) - 1>> can be used to get its length in
 bytes.
 
-=for apidoc AmU|placeholder|REPLACEMENT_CHARACTER_UTF8
+=for apidoc AmnU|const char *|REPLACEMENT_CHARACTER_UTF8
 
 This is a macro that evaluates to a string constant of the  UTF-8 bytes that
 define the Unicode REPLACEMENT CHARACTER (U+FFFD) for the platform that perl