perlapi: Add 'apidoc_flag' capability

This is meant to easily document the flags a function accepts or
returns.

Currently this only is used for generating X<> entries for the flags,
but it allows replacing (in the next commit) the previous, clumsier,
method used that does the same thing.

And it allows for future enhancements, including generating tests by
Devel::PPPort and automatic text added by autodoc.

Author: khwilliamson

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

embed.fnc

@@ -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.,