Add 'apidoc_flag' to perlapi generation

autodoc.pl

@@ -84,6 +84,9 @@
 # apidoc_item
 my $item_flags_re = qr/[dD fF mM nN oO pT uU Wx;]/xx;
 
+# Only certain flags are acceptable for apidoc_flag
+my $flag_flags_re = qr/[ A C dD eE h m n p u X ] /xx;
+
 # Certain functions have plain and no_context versions, and meet the criteria
 # stated here.  Each of their pods has been modified to have a marker line
 # which this program replaces by this wording.  This way we can tweak the
@@ -102,7 +105,8 @@
               APIDOC_DEFN        =>  1,
               PLAIN_APIDOC       =>  2,
               APIDOC_ITEM        =>  3,
-              APIDOC_SECTION     =>  4,
+              APIDOC_FLAG        =>  4,
+              APIDOC_SECTION     =>  5,
 
               # This is the line type used for elements parsed in config.h.
               # Since that file is parsed after everything else, everything is
@@ -112,7 +116,7 @@
               # doesn't have to get involved.  There are just a few of these,
               # with little likelihood of changes needed.  They were manually
               # added to handy.h via 51b56f5c7c7.
-              CONDITIONAL_APIDOC =>  5,
+              CONDITIONAL_APIDOC =>  6,
              };
 
 my $config_h = 'config.h';
@@ -789,7 +793,9 @@ ($file, $line_num, $input, $is_file_C)
                        ? APIDOC_DEFN
                        : ($type_name eq 'section')
                          ? APIDOC_SECTION
-                         : ILLEGAL_APIDOC;
+                         : ($type_name eq 'flag')
+                           ? APIDOC_FLAG
+                           : ILLEGAL_APIDOC;
 
         my $mostly_proper_form =
                    (   $type != ILLEGAL_APIDOC
@@ -1007,8 +1013,8 @@ ($fh, $file)
 
             push @items, $leader_ref;
 
-            # Now look for any 'apidoc_item' lines.  These are in a block
-            # consisting solely of them, or all-blank lines
+            # Now look for any 'apidoc_(flag|item)' lines.  These are in a
+            # block consisting solely of them, or all-blank lines
             while (1) {
                 (my $item_line_type, $arg) = $get_next_line->();
                 last unless defined $item_line_type;
@@ -1019,7 +1025,40 @@ ($fh, $file)
                     next;
                 }
 
-                last unless $item_line_type == APIDOC_ITEM;
+                # Currently not much is done with these
+                if ($item_line_type == APIDOC_FLAG) {
+                    my @components = split /\|+/, $arg;
+                    my ($name, $flags);
+                    if (@components == 1) {
+                        $name = $components[0];
+                    }
+                    elsif (   @components == 2
+                           || (@components == 3 && $components[2] !~ /\S/))
+                    {
+                        $flags = $components[0];
+                        if (my $illegal = $flags =~ s/$flag_flags_re//gr) {
+                            die "[$illegal] illegal in apidoc_item "
+                            . where_from_string($file, $line_num)
+                            . " :\n$arg";
+                        }
+
+                        # Only mention the flags that go to the parent's pod
+                        next if destination_pod($flags) ne $destpod;
+
+                        $name = $components[1];
+                    }
+                    else {
+                        die "Unexpected '| in ", $arg;
+                    }
+
+
+                    # We just make an X<> entry for it.
+                    $docs{$destpod}{$section}{X_tags}{$arg} = $file;
+                    next;
+                }
+                else {
+                    last unless $item_line_type == APIDOC_ITEM;
+                }
 
                 # Reset $text; those blank lines it contains merely are
                 # separating 'apidoc_item' lines

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           
 */
 

embed.fnc

@@ -195,7 +195,7 @@
 :   NULLOK  means the called function definitely can handle this parameter
 :	    being NULL.  The reason you need to specify this at all is to tell
 :	    future maintainers that you have considered the question about the
-:	    parameter, and this is the answer.
+:	    parameter, and you have determined that this is the answer.
 :   SPTR    means that not only must this pointer parameter be non-NULL, it
 :	    points to a position in a character string, which the called
 :	    function is not to look behind.  If a parameter is marked with this
@@ -226,14 +226,14 @@
 :   In each equation all three or any two of the constraints must be present.
 :
 :   When only two constraints are present and one of them is either EPTR or
-:   EPTRQ, the difference between the remaining SPTR or MPTR becomes somewhat
-:   fuzzy; the generated assertion will be the same whichever constraint is
-:   used.  You should choose the one that makes the most sense for the
-:   semantics of the parameter.  For example, there are currently some
-:   functions with parameters named 'curpos', and no SPTR parameter exists.
-:   The name of the parameter clearly indicates it isn't necessarily the
-:   starting position of the string, so using MPTR as the constraint makes the
-:   most sense.
+:   EPTRQ, the difference between your choosing to use SPTR or MPTR for the
+:   other one becomes somewhat fuzzy; the generated assertion will be the same
+:   whichever constraint is used.  You should choose the one that makes the
+:   most sense for the semantics of the parameter.  For example, there are
+:   currently some functions with parameters named 'curpos', and no SPTR
+:   parameter exists.  The name of the parameter clearly indicates it isn't
+:   necessarily the starting position of the string, so using MPTR as the
+:   constraint makes the most sense.
 :
 :   The parameters for the function can be in any order, except if a function
 :   has multiple different character strings, all the parameters for the first
@@ -277,6 +277,7 @@
 : Scattered around the perl source are lines of the form:
 :
 :   =for apidoc name ...
+:   =for apidoc_flag name ...
 :   =for apidoc_item name ...
 :   =for apidoc_defn name ...
 :
@@ -313,6 +314,23 @@
 : listed as 'name' on each is part of the group whose head entry is the one
 : specified by 'name' on the apidoc line.
 :
+: Many functions and macros take a flags parameter in which 1 bits in various
+: positions are OR'ed together.   Each position has a name.  You should give
+: the names of each bit that the function understands by using
+:
+:   =for apidoc_flag-name
+:
+: These are to be placed, intermixed in any order, with any 'apidoc_item'
+: statements just after the plain head '=for apidoc' line.  If the function is
+: public, but some of the flags are not, you can say, for example,
+:
+:   =for apidoc_flag C|PERL_SCAN_SILENT_NON_PORTABLE
+:
+: where the 'C' could be any of the visibility flags listed at the top of this
+: file.  (Note that the term 'flag' is overloaded here.  The function has a
+: flags parameter, and the entry describing it here has a flags field to aid in
+: that description.)
+:
 : After the block of apidoc-like statements, is the text that is the
 : documentation, ending with the next =cut or '=for apidoc foo' lines.
 :
@@ -359,6 +377,8 @@
 :
 :   =for apidoc flags|return_type|name|arg1|arg2|...|argN
 :   =for apidoc_item flags|return_type|name|arg1|arg2|...|argN
+:   =for apidoc_flag name
+:   =for apidoc_flag flags|name
 :   =for apidoc_defn flags|return_type|name|arg1|arg2|...|argN
 :
 : The 'name' in any such line must not be the same as any in this file (i.e.,

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
 */
 
@@ -3656,7 +3651,11 @@ Perl_try_amagic_bin(pTHX_ int method, int flags)
 
 
 /*
-=for apidoc amagic_deref_call
+=for apidoc      amagic_deref_call
+=for apidoc_flag AMGf_noleft
+=for apidoc_flag AMGf_noright
+=for apidoc_flag AMGf_unary
+=for apidoc_flag AMGf_assign
 
 Perform C<method> overloading dereferencing on C<ref>, returning the
 dereferenced result.  C<method> must be one of the dereference operations given