From 5af38e470e5404ea35b11b729d9a03653c224ccb Mon Sep 17 00:00:00 2001
From: Karl Williamson <khw@cpan.org>
Date: Mon, 16 Dec 2019 17:02:53 -0700
Subject: [PATCH] Note that certain flags are documented

This is useful in Devel::PPPort for generating its api-info data.  That
useful feature of D:P allows someone to find out what was the first
release of Perl to have a function, macro, or flag.  And whether using
ppport.h backports it further.

I went through apidoc.pod and looked for flags that were documented but
that D:P didn't know about.  This commit adds entries for each so that
D:P can find them.
---
 cop.h      |  2 ++
 gv.c       |  7 +++++++
 hv.c       |  2 ++
 intrpvar.h |  5 +++++
 op.c       | 13 +++++++++++++
 pad.c      |  6 ++++++
 sv.c       |  4 ++++
 toke.c     |  7 +++++++
 utf8.c     | 14 ++++++++++++++
 9 files changed, 60 insertions(+)

diff --git a/cop.h b/cop.h
index 2d007b1605e5..8a91620c9ce8 100644
--- a/cop.h
+++ b/cop.h
@@ -184,6 +184,8 @@ it has not been precomputed.  Returns a mortal scalar copy of the value
 associated with the key, or C<&PL_sv_placeholder> if there is no value
 associated with the key.
 
+=for apidoc Amnh||COPHH_KEY_UTF8
+
 =cut
 */
 
diff --git a/gv.c b/gv.c
index eb4ab927febf..a90ce9b122e4 100644
--- a/gv.c
+++ b/gv.c
@@ -323,6 +323,8 @@ the return value of SvUTF8(sv).  It can also take the
 C<GV_ADDMULTI> flag, which means to pretend that the GV has been
 seen before (i.e., suppress "Used once" warnings).
 
+=for apidoc Amnh||GV_ADDMULTI
+
 =for apidoc gv_init
 
 The old form of C<gv_init_pvn()>.  It does not work with UTF-8 strings, as it
@@ -1462,6 +1464,11 @@ Note, use of C<gv_stashsv> instead of C<gv_stashpvn> where possible is strongly
 recommended for performance reasons.
 
 =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
 */
diff --git a/hv.c b/hv.c
index d34a79be7756..eccae6294c3c 100644
--- a/hv.c
+++ b/hv.c
@@ -2672,6 +2672,8 @@ 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
 */
 
diff --git a/intrpvar.h b/intrpvar.h
index 536929259055..ff238ab9ffbf 100644
--- a/intrpvar.h
+++ b/intrpvar.h
@@ -308,6 +308,11 @@ Set by the L<perlfunc/exit> operator.
 
 =back
 
+=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
 */
 
diff --git a/op.c b/op.c
index c04bdc1de1d6..07a60f61870f 100644
--- a/op.c
+++ b/op.c
@@ -6506,6 +6506,8 @@ is automatically set.  C<first> supplies an optional op to be the direct
 child of the unary op; it is consumed by this function and become part
 of the constructed op tree.
 
+=for apidoc Amnh||OPf_KIDS
+
 =cut
 */
 
@@ -8714,6 +8716,10 @@ decremented. In addition, the C<name> argument is modified.
 If C<PERL_LOADMOD_DENY> is set, the module is loaded as if with C<no> rather
 than C<use>.
 
+=for apidoc Amnh||PERL_LOADMOD_DENY
+=for apidoc Amnh||PERL_LOADMOD_NOIMPORT
+=for apidoc Amnh||PERL_LOADMOD_IMPORT_OPS
+
 =cut */
 
 void
@@ -14150,6 +14156,11 @@ referencing GV.  The resulting C<GV*> is cast to C<CV*> to be returned.
 A null pointer is returned as usual if there is no statically-determinable
 subroutine.
 
+=for apidoc Amnh||OPpEARLY_CV
+=for apidoc Amnh||OPpENTERSUB_AMPER
+=for apidoc Amnh||RV2CVOPCV_MARK_EARLY
+=for apidoc Amnh||RV2CVOPCV_RETURN_NAME_GV
+
 =cut
 */
 
@@ -14726,6 +14737,8 @@ C<gflags> is a bitset passed into C<cv_get_call_checker_flags>, in which
 only the C<CALL_CHECKER_REQUIRE_GV> bit currently has a defined meaning
 (for which see above).  All other bits should be clear.
 
+=for apidoc Amnh||CALL_CHECKER_REQUIRE_GV
+
 =for apidoc cv_get_call_checker
 
 The original form of L</cv_get_call_checker_flags>, which does not return
diff --git a/pad.c b/pad.c
index 7a03be1f87ef..2bbb0563e016 100644
--- a/pad.c
+++ b/pad.c
@@ -121,6 +121,8 @@ 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 Amnh||SVs_PADSTALE
+
 =for apidoc AmnxU|PADNAMELIST *|PL_comppad_name
 
 During compilation, this points to the array containing the names part
@@ -2265,6 +2267,8 @@ If C<flags> has the C<CV_NAME_NOTQUAL> bit set, then the package name will not b
 included.  If the first argument is neither a CV nor a GV, this flag is
 ignored (subject to change).
 
+=for apidoc Amnh||CV_NAME_NOTQUAL
+
 =cut
 */
 
@@ -2750,6 +2754,8 @@ that refer to outer lexicals.  (See also L</newPADNAMEpvn>.)  C<outer> is
 the outer pad name that this one mirrors.  The returned pad name has the
 C<PADNAMEt_OUTER> flag already set.
 
+=for apidoc Amnh||PADNAMEt_OUTER
+
 =cut
 */
 
diff --git a/sv.c b/sv.c
index 6a23ae5e9dc9..46d6b253567a 100644
--- a/sv.c
+++ b/sv.c
@@ -5489,6 +5489,10 @@ C<mg_set> on C<dsv> afterwards if appropriate.
 C<sv_catpvn> and C<sv_catpvn_nomg> are implemented
 in terms of this function.
 
+=for apidoc Amnh||SV_CATUTF8
+=for apidoc Amnh||SV_CATBYTES
+=for apidoc Amnh||SV_SMAGIC
+
 =cut
 */
 
diff --git a/toke.c b/toke.c
index 6f38a599d479..46fa0ac86cd2 100644
--- a/toke.c
+++ b/toke.c
@@ -1003,6 +1003,8 @@ buffer is currently being interpreted (L</lex_bufutf8>).  If a string
 to be inserted is available as a Perl scalar, the L</lex_stuff_sv>
 function is more convenient.
 
+=for apidoc Amnh||LEX_STUFF_UTF8
+
 =cut
 */
 
@@ -1296,6 +1298,8 @@ consumed, then it will not be discarded regardless of the flag.
 Returns true if some new text was added to the buffer, or false if the
 buffer has reached the end of the input text.
 
+=for apidoc Amnh||LEX_KEEP_PREVIOUS
+
 =cut
 */
 
@@ -12715,7 +12719,10 @@ normally resulting in a single exception at the top level of parsing
 which covers all the compilation errors that occurred.  Some compilation
 errors, however, will throw an exception immediately.
 
+=for apidoc Amnh||PARSE_OPTIONAL
+
 =cut
+
 */
 
 OP *
diff --git a/utf8.c b/utf8.c
index 7809e7b6b722..2d4c8fb8d1b2 100644
--- a/utf8.c
+++ b/utf8.c
@@ -1286,6 +1286,20 @@ All other code points corresponding to Unicode characters, including private
 use and those yet to be assigned, are never considered malformed and never
 warn.
 
+=for apidoc Amnh||UTF8_CHECK_ONLY
+=for apidoc Amnh||UTF8_DISALLOW_ILLEGAL_INTERCHANGE
+=for apidoc Amnh||UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE
+=for apidoc Amnh||UTF8_DISALLOW_SURROGATE
+=for apidoc Amnh||UTF8_DISALLOW_NONCHAR
+=for apidoc Amnh||UTF8_DISALLOW_SUPER
+=for apidoc Amnh||UTF8_WARN_ILLEGAL_INTERCHANGE
+=for apidoc Amnh||UTF8_WARN_ILLEGAL_C9_INTERCHANGE
+=for apidoc Amnh||UTF8_WARN_SURROGATE
+=for apidoc Amnh||UTF8_WARN_NONCHAR
+=for apidoc Amnh||UTF8_WARN_SUPER
+=for apidoc Amnh||UTF8_WARN_PERL_EXTENDED
+=for apidoc Amnh||UTF8_DISALLOW_PERL_EXTENDED
+
 =cut
 
 Also implemented as a macro in utf8.h