perlapi: Use new 'apidoc_flag' lines

This replaces the clumsy method used previously by the new construct
introduced in the previous commit.

Author: khwilliamson

cop.h

@@ -202,6 +202,7 @@ typedef struct refcounted_he COPHH;
 =for apidoc_item|SV *|cophh_fetch_pvn|const COPHH *cophh|const char *key|STRLEN keylen|U32 hash|U32 flags
 =for apidoc_item|SV *|cophh_fetch_pvs|const COPHH *cophh|           "key"                      |U32 flags
 =for apidoc_item|SV *|cophh_fetch_sv |const COPHH *cophh|        SV *key              |U32 hash|U32 flags
+=for apidoc_flag COPHH_KEY_UTF8
 
 These look up the entry in the cop hints hash C<cophh> with the key specified by
 C<key> (and C<keylen> in the C<pvn> form), returning that value as a mortal
@@ -226,8 +227,6 @@ whether the key octets are interpreted as UTF-8 (if set) or as Latin-1 (if
 cleared).  The C<sv> form uses the underlying SV to determine the UTF-8ness of
 the octets.
 
-=for apidoc Amnh||COPHH_KEY_UTF8
-
 =cut
 
 */

dump.c

@@ -99,6 +99,19 @@ S_append_flags(pTHX_ SV *sv, U32 flags, const struct flag_to_name *start,
 
 /*
 =for apidoc pv_escape
+=for apidoc_flag   PERL_PV_ESCAPE_ALL
+=for apidoc_flag   PERL_PV_ESCAPE_FIRSTCHAR
+=for apidoc_flag   PERL_PV_ESCAPE_NOBACKSLASH
+=for apidoc_flag   PERL_PV_ESCAPE_NOCLEAR
+=for apidoc_flag   PERL_PV_ESCAPE_NONASCII
+=for apidoc_flag   PERL_PV_ESCAPE_QUOTE
+=for apidoc_flag   PERL_PV_ESCAPE_RE
+=for apidoc_flag   PERL_PV_ESCAPE_UNI
+=for apidoc_flag   PERL_PV_ESCAPE_UNI_DETECT
+=for apidoc_flag   PERL_PV_ESCAPE_NON_WC
+=for apidoc_flag C|PERL_PV_PRETTY_REGPROP
+=for apidoc_flag C|PERL_PV_PRETTY_DUMP
+=for apidoc_flag C|PERL_PV_PRETTY_NOCLEAR
 
 Escapes at most the first C<count> chars of C<pv> and puts the results into
 C<dsv> such that the size of the escaped string will not exceed C<max> chars
@@ -141,24 +154,6 @@ character in patterns.
 
 Returns a pointer to the escaped text as held by C<dsv>.
 
-=for apidoc Amnh||PERL_PV_ESCAPE_ALL
-=for apidoc Amnh||PERL_PV_ESCAPE_FIRSTCHAR
-=for apidoc Amnh||PERL_PV_ESCAPE_NOBACKSLASH
-=for apidoc Amnh||PERL_PV_ESCAPE_NOCLEAR
-=for apidoc Amnh||PERL_PV_ESCAPE_NONASCII
-=for apidoc Amnh||PERL_PV_ESCAPE_QUOTE
-=for apidoc Amnh||PERL_PV_ESCAPE_RE
-=for apidoc Amnh||PERL_PV_ESCAPE_UNI
-=for apidoc Amnh||PERL_PV_ESCAPE_UNI_DETECT
-=for apidoc Amnh||PERL_PV_ESCAPE_NON_WC
-
-=cut
-
-Unused or not for public use
-=for apidoc Cmnh||PERL_PV_PRETTY_REGPROP
-=for apidoc Cmnh||PERL_PV_PRETTY_DUMP
-=for apidoc Cmnh||PERL_PV_PRETTY_NOCLEAR
-
 =cut
 */
 #define PV_ESCAPE_OCTBUFSIZE 32
@@ -334,7 +329,10 @@ Perl_pv_escape( pTHX_ SV *dsv, char const * const str,
     return dsv ? SvPVX(dsv) : NULL;
 }
 /*
-=for apidoc pv_pretty
+=for apidoc      pv_pretty
+=for apidoc_flag PERL_PV_PRETTY_QUOTE
+=for apidoc_flag PERL_PV_PRETTY_LTGT
+=for apidoc_flag PERL_PV_PRETTY_ELLIPSES
 
 Converts a string into something presentable, handling escaping via
 C<pv_escape()> and supporting quoting and ellipses.
@@ -355,10 +353,6 @@ any quotes or ellipses.
 
 Returns a pointer to the prettified text as held by C<dsv>.
 
-=for apidoc Amnh||PERL_PV_PRETTY_QUOTE
-=for apidoc Amnh||PERL_PV_PRETTY_LTGT
-=for apidoc Amnh||PERL_PV_PRETTY_ELLIPSES
-
 =cut           
 */
 

gv.c

@@ -335,6 +335,7 @@ Perl_cvstash_set(pTHX_ CV *cv, HV *stash)
 =for apidoc_item gv_init_pv
 =for apidoc_item gv_init_pvn
 =for apidoc_item gv_init_sv
+=for apidoc_flag GV_ADDMULTI
 
 These each convert a scalar into a typeglob.  This is an incoercible typeglob;
 assigning a reference to it will assign to one of its slots, instead of
@@ -378,8 +379,6 @@ strings, as it has no flags parameter.  Setting the C<multi> parameter to
 non-zero has the same effect as setting the C<GV_ADDMULTI> flag in the other
 forms.
 
-=for apidoc Amnh||GV_ADDMULTI
-
 =cut
 */
 
@@ -736,6 +735,8 @@ S_maybe_add_coresub(pTHX_ HV * const stash, GV *gv,
 =for apidoc_item gv_fetchmeth_pvn_autoload
 =for apidoc_item gv_fetchmeth_sv
 =for apidoc_item gv_fetchmeth_sv_autoload
+=for apidoc_flag GV_SUPER
+=for apidoc_flag GV_NOUNIVERSAL
 
 These each look for a glob with name C<name>, containing a defined subroutine,
 returning the GV of that glob if found, or C<NULL> if not.
@@ -822,9 +823,6 @@ as being in UTF-8, the extracted PV will also be.  Including C<SVf_UTF8> in
 C<flags> will force the name to be considered to be UTF-8 even if the SV is
 not so marked.
 
-=for apidoc Amnh||GV_SUPER
-=for apidoc Amnh||GV_NOUNIVERSAL
-
 =cut
 */
 
@@ -1307,6 +1305,9 @@ Perl_gv_fetchmethod_pvn_flags(pTHX_ HV *stash, const char *name, const STRLEN le
 =for apidoc_item gv_autoload_pvn
 =for apidoc_item gv_autoload_sv
 =for apidoc_item gv_autoload4
+=for apidoc_flag GV_AUTOLOAD_ISMETHOD
+=for apidoc_flag SVf_UTF8
+=for apidoc_flag GV_SUPER
 
 These each search for an C<AUTOLOAD> method, returning NULL if not found, or
 else returning a pointer to its GV, while setting the package
@@ -1344,9 +1345,6 @@ to indicate, if set, to skip searching for the name in C<stash>.
 
 =cut
 
-=for apidoc Amnh||GV_AUTOLOAD_ISMETHOD
-=for apidoc Amnh||SVf_UTF8
-=for apidoc Amnh||GV_SUPER
 */
 
 GV*
@@ -1582,6 +1580,12 @@ S_require_tie_mod(pTHX_ GV *gv, const char varname, const char * name,
 =for apidoc_item gv_stashpvn
 =for apidoc_item gv_stashpvs
 =for apidoc_item gv_stashsv
+=for apidoc_flag GV_ADD
+=for apidoc_flag GV_NOADD_NOINIT
+=for apidoc_flag GV_NOINIT
+=for apidoc_flag GV_NOEXPAND
+=for apidoc_flag GV_ADDMG
+=for apidoc_flag SVf_UTF8
 
 Note C<gv_stashsv> is strongly preferred for performance reasons.
 
@@ -1613,13 +1617,6 @@ Flags may be one of:
 
 The most important of which are probably C<GV_ADD> and C<SVf_UTF8>.
 
-=for apidoc Amnh||GV_ADD
-=for apidoc Amnh||GV_NOADD_NOINIT
-=for apidoc Amnh||GV_NOINIT
-=for apidoc Amnh||GV_NOEXPAND
-=for apidoc Amnh||GV_ADDMG
-=for apidoc Amnh||SVf_UTF8
-
 =cut
 */
 
@@ -1678,7 +1675,8 @@ S_gv_stashpvn_internal(pTHX_ const char *name, U32 namelen, I32 flags)
 }
 
 /*
-=for apidoc gv_stashsvpvn_cached
+=for apidoc        gv_stashsvpvn_cached
+=for apidoc_flag E|GV_CACHE_ONLY
 
 Returns a pointer to the stash for a specified package, possibly
 cached.  Implements both L<perlapi/C<gv_stashpvn>> and
@@ -1692,8 +1690,6 @@ cache; see L<perlapi/C<gv_stashpvn>> for details on the other C<flags>.
 Note it is strongly preferred for C<namesv> to be non-null, for performance
 reasons.
 
-=for apidoc Emnh||GV_CACHE_ONLY
-
 =cut
 */
 
@@ -2505,6 +2501,15 @@ S_maybe_multimagic_gv(pTHX_ GV *gv, const char *name, const svtype sv_type)
 =for apidoc_item gv_fetchpvs
 =for apidoc_item gv_fetchsv
 =for apidoc_item gv_fetchsv_nomg
+=for apidoc_flag GV_ADD
+=for apidoc_flag GV_ADDMG
+=for apidoc_flag GV_ADDMULTI
+=for apidoc_flag GV_ADDWARN
+=for apidoc_flag GV_NOINIT
+=for apidoc_flag GV_NOADD_NOINIT
+=for apidoc_flag GV_NOTQUAL
+=for apidoc_flag GV_NO_SVGMAGIC
+=for apidoc_flag SVf_UTF8
 
 These all return the GV of type C<sv_type> whose name is given by the inputs,
 or NULL if no GV of that name and type could be found.  See L<perlguts/Stashes
@@ -2553,16 +2558,6 @@ the input C<name> SV.  The only difference between these two forms is that
 with C<gv_fetchsv_nomg>.  Including C<GV_NO_SVGMAGIC> in the C<flags> parameter
 to C<gv_fetchsv> makes it behave identically to C<gv_fetchsv_nomg>.
 
-=for apidoc Amnh||GV_ADD
-=for apidoc Amnh||GV_ADDMG
-=for apidoc Amnh||GV_ADDMULTI
-=for apidoc Amnh||GV_ADDWARN
-=for apidoc Amnh||GV_NOINIT
-=for apidoc Amnh||GV_NOADD_NOINIT
-=for apidoc Amnh||GV_NOTQUAL
-=for apidoc Amnh||GV_NO_SVGMAGIC
-=for apidoc Amnh||SVf_UTF8
-
 =cut
 */
 

hv.c

@@ -2639,6 +2639,7 @@ Perl_hv_eiter_set(pTHX_ HV *hv, HE *eiter) {
 /*
 =for apidoc      hv_name_set
 =for apidoc_item hv_name_sets
+=for apidoc_flag HV_NAME_SETALL
 
 These each set the name of stash C<hv> to the specified name.
 
@@ -2656,8 +2657,6 @@ otherwise not.
 If C<HV_NAME_SETALL> is set in C<flags>, both the name and the effective name
 are set.
 
-=for apidoc Amnh||HV_NAME_SETALL
-
 =cut
 */
 
@@ -2926,7 +2925,8 @@ Perl_hv_kill_backrefs(pTHX_ HV *hv) {
 /*
 hv_iternext is implemented as a macro in hv.h
 
-=for apidoc hv_iternext
+=for apidoc      hv_iternext
+=for apidoc_flag HV_ITERNEXT_WANTPLACEHOLDERS
 
 Returns entries from a hash iterator.  See C<L</hv_iterinit>>.
 
@@ -2950,8 +2950,6 @@ C<&PL_sv_placeholder>.  Note that the implementation of placeholders and
 restricted hashes may change, and the implementation currently is
 insufficiently abstracted for any change to be tidy.
 
-=for apidoc Amnh||HV_ITERNEXT_WANTPLACEHOLDERS
-
 =cut
 */
 

intrpvar.h

@@ -349,6 +349,10 @@ PERLVARI(I, dumpindent,	U16,	4)	/* number of blanks per dump
 /*
 =for apidoc_section $embedding
 =for apidoc Amn|U8|PL_exit_flags
+=for apidoc_flag PERL_EXIT_EXPECTED
+=for apidoc_flag PERL_EXIT_ABORT
+=for apidoc_flag PERL_EXIT_DESTRUCT_END
+=for apidoc_flag PERL_EXIT_WARN
 
 Contains flags controlling perl's behaviour on exit():
 
@@ -379,11 +383,6 @@ On threaded perls, each thread has an independent copy of this variable;
 each initialized at creation time with the current value of the creating
 thread's copy.
 
-=for apidoc Amnh||PERL_EXIT_EXPECTED
-=for apidoc Amnh||PERL_EXIT_ABORT
-=for apidoc Amnh||PERL_EXIT_DESTRUCT_END
-=for apidoc Amnh||PERL_EXIT_WARN
-
 =cut
 */
 

numeric.c

@@ -218,6 +218,10 @@ Perl_cast_uv(NV f)
 
 /*
 =for apidoc grok_bin
+=for apidoc_flag PERL_SCAN_ALLOW_UNDERSCORES
+=for apidoc_flag PERL_SCAN_DISALLOW_PREFIX
+=for apidoc_flag PERL_SCAN_GREATER_THAN_UV_MAX
+=for apidoc_flag PERL_SCAN_SILENT_ILLDIGIT
 
 converts a string representing a binary number to numeric form.
 
@@ -242,11 +246,6 @@ If C<PERL_SCAN_ALLOW_UNDERSCORES> is set in C<*flags> then any or all pairs of
 digits may be separated from each other by a single underscore; also a single
 leading underscore is accepted.
 
-=for apidoc Amnh||PERL_SCAN_ALLOW_UNDERSCORES
-=for apidoc Amnh||PERL_SCAN_DISALLOW_PREFIX
-=for apidoc Amnh||PERL_SCAN_GREATER_THAN_UV_MAX
-=for apidoc Amnh||PERL_SCAN_SILENT_ILLDIGIT
-
 =cut
 
 Not documented yet because experimental is C<PERL_SCAN_SILENT_NON_PORTABLE
@@ -745,6 +744,12 @@ Perl_grok_numeric_radix(pTHX_ const char **sp, const char *send)
 
 /*
 =for apidoc grok_infnan
+=for apidoc_flag IS_NUMBER_GREATER_THAN_UV_MAX
+=for apidoc_flag IS_NUMBER_INFINITY
+=for apidoc_flag IS_NUMBER_IN_UV
+=for apidoc_flag IS_NUMBER_NAN
+=for apidoc_flag IS_NUMBER_NEG
+=for apidoc_flag IS_NUMBER_NOT_INT
 
 Helper for C<grok_number()>, accepts various ways of spelling "infinity"
 or "not a number", and returns one of the following flag combinations:
@@ -761,13 +766,6 @@ If an infinity or a not-a-number is recognized, C<*sp> will point to
 one byte past the end of the recognized string.  If the recognition fails,
 zero is returned, and C<*sp> will not move.
 
-=for apidoc Amnh||IS_NUMBER_GREATER_THAN_UV_MAX
-=for apidoc Amnh||IS_NUMBER_INFINITY
-=for apidoc Amnh||IS_NUMBER_IN_UV
-=for apidoc Amnh||IS_NUMBER_NAN
-=for apidoc Amnh||IS_NUMBER_NEG
-=for apidoc Amnh||IS_NUMBER_NOT_INT
-
 =cut
 */
 
@@ -1016,6 +1014,14 @@ Perl_grok_infnan(pTHX_ const char** sp, const char* send)
 
 =for apidoc      grok_number
 =for apidoc_item grok_number_flags
+=for apidoc_flag IS_NUMBER_GREATER_THAN_UV_MAX
+=for apidoc_flag IS_NUMBER_INFINITY
+=for apidoc_flag IS_NUMBER_IN_UV
+=for apidoc_flag IS_NUMBER_NAN
+=for apidoc_flag IS_NUMBER_NEG
+=for apidoc_flag IS_NUMBER_NOT_INT
+=for apidoc_flag IS_NUMBER_TRAILING
+=for apidoc_flag PERL_SCAN_TRAILING
 
 Look for a base 10 number in the C<len> bytes starting at C<pv>.  If one isn't
 found, return 0; otherwise return its type (and optionally its value).  In
@@ -1060,15 +1066,6 @@ In C<grok_number_flags> when C<flags> contains the C<PERL_SCAN_TRAILING>
 bit, and trailing non-numeric text was found, the returned type will include
 the C<IS_NUMBER_TRAILING> bit.
 
-=for apidoc Amnh||IS_NUMBER_GREATER_THAN_UV_MAX
-=for apidoc Amnh||IS_NUMBER_INFINITY
-=for apidoc Amnh||IS_NUMBER_IN_UV
-=for apidoc Amnh||IS_NUMBER_NAN
-=for apidoc Amnh||IS_NUMBER_NEG
-=for apidoc Amnh||IS_NUMBER_NOT_INT
-=for apidoc Amnh||IS_NUMBER_TRAILING
-=for apidoc Amnh||PERL_SCAN_TRAILING
-
 =cut
  */
 int