Commit 7838a46329 for perl

commit 7838a4632996eab80c11128f9cb23a31f765e574
Author: Karl Williamson <khw@cpan.org>
Date:   Mon Oct 5 16:20:22 2026 -0600

    regcharclass.pl: Autogenerate perlintern entries

    The information we already have enables generation of pretty decent
    documentation for all the macros here, and it should be quite easy as
    well for any new ones that might come along

diff --git a/embed.h b/embed.h
index 3bf7d416da..7ec396f968 100644
--- a/embed.h
+++ b/embed.h
@@ -41,7 +41,6 @@
 #   undef F_sqrt_amg
 #   undef GET_aTHX_if_NULL
 #   undef HASATTRIBUTE_UNINITIALIZED
-#   undef is_WORD_BUT_NONCONT_safe
 #   undef isFOO_or_UNDERSCORE_
 #   undef isIDCONT_lazy_if_safe
 #   undef KEY_equ
diff --git a/regcharclass.h b/regcharclass.h
index 5f73fdd6b0..52e0774fc4 100644
--- a/regcharclass.h
+++ b/regcharclass.h
@@ -14,6 +14,9 @@
  * changed or removed without notice.
  */

+/*
+=for apidoc_section $classification
+*/

 #ifndef PERL_REGCHARCLASS_H_ /* Guard against nested #includes */
 #  define PERL_REGCHARCLASS_H_
@@ -26,6 +29,30 @@
 	"\x0D\x0A"      # CRLF - Network (Windows) line ending
 	\p{VertSpace}
 */
+/*
+=for apidoc CT|STRLEN|is_LNBREAK_safe|const U8 * s|const U8 * e|bool is_utf8
+A few Unicode characters or character sequences act as line terminators.
+C<\R> in a regular expression pattern matches them.
+
+This returns non-zero if the input byte(s) form such a character sequence.
+
+If C<is_utf8> is C<false>, the input is considered to be
+Latin1, and the single byte at C<*s> is examined.
+
+If C<is_utf8> is C<true>, the input is considered to be UTF-8,
+and the
+sequence of bytes starting at C<s>, and extending no further than S<C<e> - 1>
+are examined.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+character sequence actually occupies.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_LNBREAK_safe(s,e,is_utf8)                                        \
 ( (STRLEN)( ((e)-(s) > 2) ?                                                 \
@@ -51,6 +78,24 @@
     : 0 )                                                                   \
 : 0 ) )

+/*
+=for apidoc CT|STRLEN|is_LNBREAK_utf8_safe|const U8 * s|const U8 * e
+A few Unicode characters or character sequences act as line terminators.
+C<\R> in a regular expression pattern matches them.
+
+This returns non-zero if the
+sequence of bytes starting at C<s>, and extending no further than S<C<e> - 1>
+form a valid UTF-8 representation of such a character sequence.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+character sequence actually occupies.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_LNBREAK_utf8_safe(s,e)                                           \
 ( (STRLEN)( ((e)-(s) > 2) ?                                                 \
@@ -69,6 +114,24 @@
     ( inRANGE_helper_(U8, ((const U8*)s)[0], '\n', '\r') )                  \
 : 0 ) )

+/*
+=for apidoc CT|STRLEN|is_LNBREAK_latin1_safe|const U8 * s|const U8 * e
+A few Unicode characters or character sequences act as line terminators.
+C<\R> in a regular expression pattern matches them.
+
+This returns non-zero if the
+sequence of bytes starting at C<s>, and extending no further than S<C<e> - 1>
+form a valid UTF-8 representation of such a character sequence that is entirely in the Latin1-range.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+character sequence actually occupies.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_LNBREAK_latin1_safe(s,e)                                         \
 ( (STRLEN)( ((e)-(s) > 1) ?                                                 \
@@ -85,6 +148,27 @@

 	\p{HorizSpace}
 */
+/*
+=for apidoc CT|STRLEN|is_HORIZWS_high|const U8 * s
+A few Unicode characters are treated as horizontal space.
+
+This returns non-zero if the
+sequence of the next few bytes starting at C<s>
+form a valid UTF-8 representation of such a character that is in the above-Latin1 range.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+character actually occupies.
+
+You need to be sure that the bytes at C<s> comprise at least
+one complete character before calling this; otherwise this
+could read beyond its end.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_HORIZWS_high(s)                                                  \
 ( (STRLEN)( ( 0xE1 == ((const U8*)s)[0] ) ?                                 \
@@ -95,6 +179,20 @@
     : ( ( 0x81 == ((const U8*)s)[1] ) && ( 0x9F == ((const U8*)s)[2] ) ) ? 3 : 0 )\
 : ( ( ( 0xE3 == ((const U8*)s)[0] ) && ( 0x80 == ((const U8*)s)[1] ) ) && ( 0x80 == ((const U8*)s)[2] ) ) ? 3 : 0 ) )

+/*
+=for apidoc CT|STRLEN|is_HORIZWS_cp_high|UV cp
+A few Unicode characters are treated as horizontal space.
+
+This returns non-zero if code point C<cp> is
+such a character that is in the above-Latin1 range.
+
+Otherwise, it returns zero.
+
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_HORIZWS_cp_high(cp)                                              \
 ( (STRLEN)( 0x1680 == cp || ( 0x1680 < cp &&                                \
@@ -107,10 +205,45 @@

 	\p{VertSpace}
 */
+/*
+=for apidoc CT|STRLEN|is_VERTWS_high|const U8 * s
+A few Unicode characters are treated as vertical space.
+
+This returns non-zero if the
+sequence of the next few bytes starting at C<s>
+form a valid UTF-8 representation of such a character that is in the above-Latin1 range.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+character actually occupies.
+
+You need to be sure that the bytes at C<s> comprise at least
+one complete character before calling this; otherwise this
+could read beyond its end.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_VERTWS_high(s)                                                   \
 ( (STRLEN)( ( ( ( 0xE2 == ((const U8*)s)[0] ) && ( 0x80 == ((const U8*)s)[1] ) ) && ( inRANGE_helper_(U8, ((const U8*)s)[2], 0xA8, 0xA9) ) ) ? 3 : 0 ) )

+/*
+=for apidoc CT|STRLEN|is_VERTWS_cp_high|UV cp
+A few Unicode characters are treated as vertical space.
+
+This returns non-zero if code point C<cp> is
+such a character that is in the above-Latin1 range.
+
+Otherwise, it returns zero.
+
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_VERTWS_cp_high(cp)                                               \
 ( (STRLEN)( inRANGE_helper_(UV, cp, 0x2028, 0x2029) ) )
@@ -120,6 +253,27 @@

 	\p{XDigit}
 */
+/*
+=for apidoc CT|STRLEN|is_XDIGIT_high|const U8 * s
+A few Unicode characters are treated as hexadecimal digits.
+
+This returns non-zero if the
+sequence of the next few bytes starting at C<s>
+form a valid UTF-8 representation of such a character that is in the above-Latin1 range.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+character actually occupies.
+
+You need to be sure that the bytes at C<s> comprise at least
+one complete character before calling this; otherwise this
+could read beyond its end.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_XDIGIT_high(s)                                                   \
 ( (STRLEN)( ( 0xEF == ((const U8*)s)[0] ) ?                                 \
@@ -128,6 +282,20 @@
     : ( ( 0xBD == ((const U8*)s)[1] ) && ( inRANGE_helper_(U8, ((const U8*)s)[2], 0x81, 0x86) ) ) ? 3 : 0 )\
 : 0 ) )

+/*
+=for apidoc CT|STRLEN|is_XDIGIT_cp_high|UV cp
+A few Unicode characters are treated as hexadecimal digits.
+
+This returns non-zero if code point C<cp> is
+such a character that is in the above-Latin1 range.
+
+Otherwise, it returns zero.
+
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_XDIGIT_cp_high(cp)                                               \
 ( (STRLEN)( inRANGE_helper_(UV, cp, 0xFF10, 0xFF19) || ( 0xFF19 < cp &&     \
@@ -138,6 +306,25 @@

 	\p{XPerlSpace}
 */
+/*
+=for apidoc CT|STRLEN|is_XPERLSPACE_high|const U8 * s
+This returns non-zero if the
+sequence of the next few bytes starting at C<s>
+form a valid UTF-8 representation of an above-Latin1 range character that matches \p{XPerlSpace}.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+character actually occupies.
+
+You need to be sure that the bytes at C<s> comprise at least
+one complete character before calling this; otherwise this
+could read beyond its end.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_XPERLSPACE_high(s)                                               \
 ( (STRLEN)( ( 0xE1 == ((const U8*)s)[0] ) ?                                 \
@@ -148,6 +335,18 @@
     : ( ( 0x81 == ((const U8*)s)[1] ) && ( 0x9F == ((const U8*)s)[2] ) ) ? 3 : 0 )\
 : ( ( ( 0xE3 == ((const U8*)s)[0] ) && ( 0x80 == ((const U8*)s)[1] ) ) && ( 0x80 == ((const U8*)s)[2] ) ) ? 3 : 0 ) )

+/*
+=for apidoc CT|STRLEN|is_XPERLSPACE_cp_high|UV cp
+This returns non-zero if code point C<cp> is
+an above-Latin1 range character that matches \p{XPerlSpace}.
+
+Otherwise, it returns zero.
+
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_XPERLSPACE_cp_high(cp)                                           \
 ( (STRLEN)( 0x1680 == cp || ( 0x1680 < cp &&                                \
@@ -161,6 +360,23 @@

 	\p{XPerlSpace}
 */
+/*
+=for apidoc CT|STRLEN|is_SPACE_utf8_safe_backwards|const U8 * s|const U8 * e
+Some Unicode characters are treated as space, both horizontal and vertical.
+
+This returns non-zero if the
+sequence of bytes starting at C<s>, and extending no further BACK than S<C<e> + 1>
+form a valid UTF-8 representation of such a character.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+character actually occupies.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_SPACE_utf8_safe_backwards(s,e)                                   \
 ( (STRLEN)( ((s) - (e) > 2) ?                                               \
@@ -190,6 +406,26 @@

 	\p{_Perl_Nchar}
 */
+/*
+=for apidoc CT|STRLEN|is_NONCHAR_utf8_safe|const U8 * s|const U8 * e
+Unicode has 66 noncharacter codepoints.  These are not assigned to characters,
+and are guaranteed never to be, so that an application can treat them as
+reserved for its internal use.
+
+
+This returns non-zero if the
+sequence of bytes starting at C<s>, and extending no further than S<C<e> - 1>
+form a valid UTF-8 representation of such a code point.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+code point actually occupies.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_NONCHAR_utf8_safe(s,e)                                           \
 ( (STRLEN)( ( ( LIKELY((e) > (s)) ) && ( LIKELY(((e) - (s)) >= UTF8SKIP(s)) ) ) ? ( ( 0xEF == ((const U8*)s)[0] ) ?\
@@ -208,6 +444,39 @@
 	0xFDD0 - 0xFDEF
 	0xFFFE - 0xFFFF
 */
+/*
+=for apidoc CT|STRLEN|is_SHORTER_NON_CHARS_utf8|const U8 * s
+Unicode has 66 noncharacter codepoints.  These are not assigned to characters,
+and are guaranteed never to be, so that an application can treat them as
+reserved for its internal use.
+
+
+All noncharacter code points can be represented in UTF-8 by sequences of bytes
+consisting of either of two lengths: a shorter length, and a longer one.
+(The actual count is different on ASCII versus EBCDIC platforms.)
+
+This macro exists because it is sometimes convenient to consider the two sets
+individually.
+
+It handles the shorter ones.
+
+This returns non-zero if the
+sequence of the next few bytes starting at C<s>
+form a valid UTF-8 representation of such a code point.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+code point actually occupies.
+
+You need to be sure that the bytes at C<s> comprise at least
+one complete code point before calling this; otherwise this
+could read beyond its end.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_SHORTER_NON_CHARS_utf8(s)                                        \
 ( (STRLEN)( ( 0xEF == ((const U8*)s)[0] ) ?                                 \
@@ -236,6 +505,39 @@
 	0xFFFFE - 0xFFFFF
 	0x10FFFE - 0x10FFFF
 */
+/*
+=for apidoc CT|STRLEN|is_LARGER_NON_CHARS_utf8|const U8 * s
+Unicode has 66 noncharacter codepoints.  These are not assigned to characters,
+and are guaranteed never to be, so that an application can treat them as
+reserved for its internal use.
+
+
+All noncharacter code points can be represented in UTF-8 by sequences of bytes
+consisting of either of two lengths: a shorter length, and a longer one.
+(The actual count is different on ASCII versus EBCDIC platforms.)
+
+This macro exists because it is sometimes convenient to consider the two sets
+individually.
+
+It handles the longer ones.
+
+This returns non-zero if the
+sequence of the next few bytes starting at C<s>
+form a valid UTF-8 representation of such a code point.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+code point actually occupies.
+
+You need to be sure that the bytes at C<s> comprise at least
+one complete code point before calling this; otherwise this
+could read beyond its end.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_LARGER_NON_CHARS_utf8(s)                                         \
 ( (STRLEN)( ( 0xF0 == ((const U8*)s)[0] ) ?                                 \
@@ -249,10 +551,50 @@

 	\p{_Perl_Surrogate}
 */
+/*
+=for apidoc CT|STRLEN|is_SURROGATE_utf8|const U8 * s
+Surrogate code points enable UTF-16 to be extended to be able to represent all
+Unicode code points
+
+This returns non-zero if the
+sequence of the next few bytes starting at C<s>
+form a valid UTF-8 representation of such a code point.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+code point actually occupies.
+
+You need to be sure that the bytes at C<s> comprise at least
+one complete code point before calling this; otherwise this
+could read beyond its end.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_SURROGATE_utf8(s)                                                \
 ( (STRLEN)( ( ( 0xED == ((const U8*)s)[0] ) && ( inRANGE_helper_(U8, ((const U8*)s)[1], 0xA0, 0xBF) ) ) ? 3 : 0 ) )

+/*
+=for apidoc CT|STRLEN|is_SURROGATE_utf8_safe|const U8 * s|const U8 * e
+Surrogate code points enable UTF-16 to be extended to be able to represent all
+Unicode code points
+
+This returns non-zero if the
+sequence of bytes starting at C<s>, and extending no further than S<C<e> - 1>
+form a valid UTF-8 representation of such a code point.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+code point actually occupies.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_SURROGATE_utf8_safe(s,e)                                         \
 ( (STRLEN)( ( ( ( ( ((e) - (s)) >= 3 ) && ( 0xED == ((const U8*)s)[0] ) ) && ( inRANGE_helper_(U8, ((const U8*)s)[1], 0xA0, 0xBF) ) ) && ( inRANGE_helper_(U8, ((const U8*)s)[2], 0x80, 0xBF) ) ) ? 3 : 0 ) )
@@ -262,6 +604,28 @@

 	\p{_Perl_Quotemeta}
 */
+/*
+=for apidoc CT|STRLEN|is_QUOTEMETA_high|const U8 * s
+Most characters in a Perl program represent themselves, but there are a few
+"meta-characters" which mean something else unless escaped in some way.
+
+This returns non-zero if the
+sequence of the next few bytes starting at C<s>
+form a valid UTF-8 representation of such a character that is in the above-Latin1 range.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+character actually occupies.
+
+You need to be sure that the bytes at C<s> comprise at least
+one complete character before calling this; otherwise this
+could read beyond its end.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_QUOTEMETA_high(s)                                                \
 ( (STRLEN)( ( 0xCD == ((const U8*)s)[0] ) ?                                 \
@@ -317,6 +681,24 @@

 	%regcharclass_multi_char_folds::multi_char_folds('u', 'a')
 */
+/*
+=for apidoc CT|STRLEN|is_MULTI_CHAR_FOLD_utf8_safe|const U8 * s|const U8 * e
+The casefold of some Unicode characters expands to two or three characters.
+
+
+This returns non-zero if the
+sequence of bytes starting at C<s>, and extending no further than S<C<e> - 1>
+form a valid UTF-8 representation of such a character sequence.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+character sequence actually occupies.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_MULTI_CHAR_FOLD_utf8_safe_part0_(s,e)                            \
 ( ( ( ((const U8*)s)[1] & 0xDF ) == 'F' ) ?                                 \
@@ -554,6 +936,26 @@
     : 0 )                                                                   \
 : ((e)-(s) > 3) ? is_MULTI_CHAR_FOLD_utf8_safe_part2_(s,e) : is_MULTI_CHAR_FOLD_utf8_safe_part3_(s,e) ) )

+/*
+=for apidoc CT|UV|what_MULTI_CHAR_FOLD_utf8_safe|const U8 * s|const U8 * e
+The casefold of some Unicode characters expands to two or three characters.
+
+
+This returns the code point that the input byte(s) form if
+they match such a character sequence.
+
+It returns zero otherwise.  Fortunately C<NUL> is not matched
+by this, or else disambiguation would be required.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+character sequence actually occupies.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define what_MULTI_CHAR_FOLD_utf8_safe_part0_(s,e)                          \
 ( ( 0x81 == ((const U8*)s)[1] ) ?                                           \
@@ -985,6 +1387,24 @@

 	%regcharclass_multi_char_folds::multi_char_folds('l', 'a')
 */
+/*
+=for apidoc CT|STRLEN|is_MULTI_CHAR_FOLD_latin1_safe|const U8 * s|const U8 * e
+The casefold of some Unicode characters expands to two or three characters.
+
+
+This returns non-zero if the
+sequence of bytes starting at C<s>, and extending no further than S<C<e> - 1>
+form a valid UTF-8 representation of such a character sequence that is entirely in the Latin1-range.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+character sequence actually occupies.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_MULTI_CHAR_FOLD_latin1_safe(s,e)                                 \
 ( (STRLEN)( ((e)-(s) > 2) ?                                                 \
@@ -999,6 +1419,26 @@
     : ( ( ( ((const U8*)s)[0] & 0xDF ) == 'S' ) && ( inRANGE_helper_(U8, ((const U8*)s)[1], 'S', 'T') || inRANGE_helper_(U8, ((const U8*)s)[1], 's', 't') ) ) ? 2 : 0 )\
 : 0 ) )

+/*
+=for apidoc CT|UV|what_MULTI_CHAR_FOLD_latin1_safe|const U8 * s|const U8 * e
+The casefold of some Unicode characters expands to two or three characters.
+
+
+This returns the code point that the input byte(s) form if
+they match such a character sequence that is entirely in the Latin1-range.
+
+It returns zero otherwise.  Fortunately C<NUL> is not matched
+by this, or else disambiguation would be required.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+character sequence actually occupies.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define what_MULTI_CHAR_FOLD_latin1_safe(s,e)                               \
 ( ((e)-(s) > 2) ?                                                           \
@@ -1028,6 +1468,24 @@

 	%regcharclass_multi_char_folds::multi_char_folds('u', '3')
 */
+/*
+=for apidoc CT|STRLEN|is_THREE_CHAR_FOLD_utf8_safe|const U8 * s|const U8 * e
+The casefold of a few Unicode characters expands to three characters.
+
+
+This returns non-zero if the
+sequence of bytes starting at C<s>, and extending no further than S<C<e> - 1>
+form a valid UTF-8 representation of such a character sequence.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+character sequence actually occupies.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_THREE_CHAR_FOLD_utf8_safe(s,e)                                   \
 ( (STRLEN)( ((e)-(s) > 5) ?                                                 \
@@ -1053,6 +1511,24 @@

 	%regcharclass_multi_char_folds::multi_char_folds('l', '3')
 */
+/*
+=for apidoc CT|STRLEN|is_THREE_CHAR_FOLD_latin1_safe|const U8 * s|const U8 * e
+The casefold of a few Unicode characters expands to three characters.
+
+
+This returns non-zero if the
+sequence of bytes starting at C<s>, and extending no further than S<C<e> - 1>
+form a valid UTF-8 representation of such a character sequence that is entirely in the Latin1-range.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+character sequence actually occupies.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_THREE_CHAR_FOLD_latin1_safe(s,e)                                 \
 ( (STRLEN)( ( ( ( ( ((e) - (s)) >= 3 ) && ( ( ((const U8*)s)[0] & 0xDF ) == 'F' ) ) && ( ( ((const U8*)s)[1] & 0xDF ) == 'F' ) ) && ( ( ( ((const U8*)s)[2] & 0xDF ) == 'I' ) || ( ( ((const U8*)s)[2] & 0xDF ) == 'L' ) ) ) ? 3 : 0 ) )
@@ -1062,6 +1538,25 @@

 	%regcharclass_multi_char_folds::multi_char_folds('u', 'h')
 */
+/*
+=for apidoc CT|STRLEN|is_THREE_CHAR_FOLD_HEAD_utf8_safe|const U8 * s|const U8 * e
+The casefold of a few Unicode characters expands to three characters.
+
+Sometimes we are interested in just the first two of these.
+
+This returns non-zero if the
+sequence of bytes starting at C<s>, and extending no further than S<C<e> - 1>
+form a valid UTF-8 representation of such a character sequence.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+character sequence actually occupies.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_THREE_CHAR_FOLD_HEAD_utf8_safe(s,e)                              \
 ( (STRLEN)( ((e)-(s) > 3) ?                                                 \
@@ -1134,6 +1629,25 @@

 	%regcharclass_multi_char_folds::multi_char_folds('l', 'h')
 */
+/*
+=for apidoc CT|STRLEN|is_THREE_CHAR_FOLD_HEAD_latin1_safe|const U8 * s|const U8 * e
+The casefold of a few Unicode characters expands to three characters.
+
+Sometimes we are interested in just the first two of these.
+
+This returns non-zero if the
+sequence of bytes starting at C<s>, and extending no further than S<C<e> - 1>
+form a valid UTF-8 representation of such a character sequence that is entirely in the Latin1-range.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+character sequence actually occupies.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_THREE_CHAR_FOLD_HEAD_latin1_safe(s,e)                            \
 ( (STRLEN)( ((e)-(s) > 1) ?                                                 \
@@ -1150,6 +1664,28 @@

 	\p{_Perl_Folds_To_Multi_Char}
 */
+/*
+=for apidoc CT|STRLEN|is_FOLDS_TO_MULTI_utf8|const U8 * s
+The casefold of some Unicode characters expands to two or three characters.
+
+
+This returns non-zero if the
+sequence of the next few bytes starting at C<s>
+form a valid UTF-8 representation of such a character.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+character actually occupies.
+
+You need to be sure that the bytes at C<s> comprise at least
+one complete character before calling this; otherwise this
+could read beyond its end.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_FOLDS_TO_MULTI_utf8(s)                                           \
 ( (STRLEN)( ( 0xC3 == ((const U8*)s)[0] ) ?                                 \
@@ -1179,6 +1715,29 @@

 	\p{_Perl_Problematic_Locale_Folds}
 */
+/*
+=for apidoc CT|STRLEN|is_PROBLEMATIC_LOCALE_FOLD_utf8|const U8 * s
+The casefold of most Unicode characters is straight forward, but for some, it
+is problematic in some way.
+
+
+This returns non-zero if the
+sequence of the next few bytes starting at C<s>
+form a valid UTF-8 representation of such a character.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+character actually occupies.
+
+You need to be sure that the bytes at C<s> comprise at least
+one complete character before calling this; otherwise this
+could read beyond its end.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_PROBLEMATIC_LOCALE_FOLD_utf8(s)                                  \
 ( (STRLEN)( ( ((const U8*)s)[0] <= 0x7F ) ? 1                               \
@@ -1202,6 +1761,22 @@
     ( ( ( 0xAC == ((const U8*)s)[1] ) && ( inRANGE_helper_(U8, ((const U8*)s)[2], 0x80, 0x86) ) ) ? 3 : 0 )\
 : ( ( ( ( 0xF0 == ((const U8*)s)[0] ) && ( 0x9D == ((const U8*)s)[1] ) ) && ( 0xBE == ((const U8*)s)[2] ) ) && ( 0x95 == ((const U8*)s)[3] ) ) ? 4 : 0 ) )

+/*
+=for apidoc CT|STRLEN|is_PROBLEMATIC_LOCALE_FOLD_cp|UV cp
+The casefold of most Unicode characters is straight forward, but for some, it
+is problematic in some way.
+
+
+This returns non-zero if code point C<cp> is
+such a character.
+
+Otherwise, it returns zero.
+
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_PROBLEMATIC_LOCALE_FOLD_cp(cp)                                   \
 ( (STRLEN)( cp <= 0xFF || ( 0xFF < cp &&                                    \
@@ -1223,6 +1798,31 @@

 	\p{_Perl_Problematic_Locale_Foldeds_Start}
 */
+/*
+=for apidoc CT|STRLEN|is_PROBLEMATIC_LOCALE_FOLDEDS_START_utf8|const U8 * s
+The casefold of most Unicode characters is straight forward, but for some, it
+is problematic in some way.
+
+Some times we are interested in just the first character of those that fold to
+a sequence of more than one.
+
+This returns non-zero if the
+sequence of the next few bytes starting at C<s>
+form a valid UTF-8 representation of such a character.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+character actually occupies.
+
+You need to be sure that the bytes at C<s> comprise at least
+one complete character before calling this; otherwise this
+could read beyond its end.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_PROBLEMATIC_LOCALE_FOLDEDS_START_utf8(s)                         \
 ( (STRLEN)( ( ((const U8*)s)[0] <= 0x7F ) ? 1                               \
@@ -1246,6 +1846,24 @@
     ( ( ( 0xAC == ((const U8*)s)[1] ) && ( inRANGE_helper_(U8, ((const U8*)s)[2], 0x80, 0x86) ) ) ? 3 : 0 )\
 : ( ( ( ( 0xF0 == ((const U8*)s)[0] ) && ( 0x9D == ((const U8*)s)[1] ) ) && ( 0xBE == ((const U8*)s)[2] ) ) && ( 0x95 == ((const U8*)s)[3] ) ) ? 4 : 0 ) )

+/*
+=for apidoc CT|STRLEN|is_PROBLEMATIC_LOCALE_FOLDEDS_START_cp|UV cp
+The casefold of most Unicode characters is straight forward, but for some, it
+is problematic in some way.
+
+Some times we are interested in just the first character of those that fold to
+a sequence of more than one.
+
+This returns non-zero if code point C<cp> is
+such a character.
+
+Otherwise, it returns zero.
+
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_PROBLEMATIC_LOCALE_FOLDEDS_START_cp(cp)                          \
 ( (STRLEN)( cp <= 0xFF || ( 0xFF < cp &&                                    \
@@ -1267,6 +1885,31 @@

 	\p{_Perl_PatWS}
 */
+/*
+=for apidoc CT|STRLEN|is_PATWS_safe|const U8 * s|const U8 * e|bool is_utf8
+Not all characters that are nominally space characters in Unicode are
+considered as such in regular expression patterns.  Sometimes we need to
+consider just the latter.
+
+This returns non-zero if the input byte(s) form such a character.
+
+If C<is_utf8> is C<false>, the input is considered to be
+Latin1, and the single byte at C<*s> is examined.
+
+If C<is_utf8> is C<true>, the input is considered to be UTF-8,
+and the
+sequence of bytes starting at C<s>, and extending no further than S<C<e> - 1>
+are examined.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+character actually occupies.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_PATWS_safe(s,e,is_utf8)                                          \
 ( (STRLEN)( ( LIKELY((e) > (s)) ) ?                                         \
@@ -1285,6 +1928,24 @@

 	0xD000 - 0xD7FF
 */
+/*
+=for apidoc CT|STRLEN|is_HANGUL_ED_utf8_safe|const U8 * s|const U8 * e
+For convenience of the implementation, certain Korean Hangul syllable characters
+have to be treated specially.
+
+This returns non-zero if the
+sequence of bytes starting at C<s>, and extending no further than S<C<e> - 1>
+form a valid UTF-8 representation of such a character.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+character actually occupies.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_HANGUL_ED_utf8_safe(s,e)                                         \
 ( (STRLEN)( ( ( ( ( ((e) - (s)) >= 3 ) && ( 0xED == ((const U8*)s)[0] ) ) && ( inRANGE_helper_(U8, ((const U8*)s)[1], 0x80, 0x9F) ) ) && ( inRANGE_helper_(U8, ((const U8*)s)[2], 0x80, 0xBF) ) ) ? 3 : 0 ) )
@@ -1294,6 +1955,30 @@

 	\p{_Perl_Word_But_NonCont}
 */
+/*
+=for apidoc CT|STRLEN|is_WORD_BUT_NONCONT_safe|const U8 * s|const U8 * e|bool is_utf8
+Some Unicode characters that match C<\w> can't be used in Perl names (such as
+identifiers and labels).
+
+This returns non-zero if the input byte(s) form such a character.
+
+If C<is_utf8> is C<false>, the input is considered to be
+Latin1, and the single byte at C<*s> is examined.
+
+If C<is_utf8> is C<true>, the input is considered to be UTF-8,
+and the
+sequence of bytes starting at C<s>, and extending no further than S<C<e> - 1>
+are examined.
+
+Otherwise, it returns zero.
+
+The value returned gives the number of bytes the matched
+character actually occupies.
+
+
+=cut
+*/
+
 /*** GENERATED CODE ***/
 #define is_WORD_BUT_NONCONT_safe(s,e,is_utf8)                               \
 ( (STRLEN)( ( ( LIKELY((e) > (s)) ) && ( LIKELY(((e) - (s)) >= UTF8SKIP(s)) ) ) ? ( ( 0xCD == ((const U8*)s)[0] ) ?\
@@ -4004,6 +4689,6 @@
  * 94644b4e53ef4f2590ef86a261dcd22ffadf79247fcc7f31c4ebf5b19111fd25 lib/unicore/mktables
  * a0079d7556b20c2de1fdc3d492797a91b8ec8a06006f94460006185cb6380962 lib/unicore/version
  * 0a6b5ab33bb1026531f816efe81aea1a8ffcd34a27cbea37dd6a70a63d73c844 regen/charset_translations.pl
- * 91ddccc1480339f823e105491df2ab793a4a03384078fd420560a36814d9407e regen/regcharclass.pl
+ * 6730b735af1d47e4c2cf01e4a202e92d3b12eaefa8990410454e96564482d9e7 regen/regcharclass.pl
  * 1ce43daf54162d0a267412453ce2a613f60f3a7631365775cc52d34213251a83 regen/regcharclass_multi_char_folds.pl
  * ex: set ro ft=c: */
diff --git a/regen/embed.pl b/regen/embed.pl
index 8095a2632a..aff09f4b13 100755
--- a/regen/embed.pl
+++ b/regen/embed.pl
@@ -846,29 +846,17 @@ my %unresolved_visibility_overrides = map { $_ => 1 } qw(
     isCHARNAME_CONT
     isCNTRL_LC_utf8
     isDIGIT_LC_utf8
-    is_FOLDS_TO_MULTI_utf8
     isGRAPH_LC_utf8
     isGV_with_GP_off
     isGV_with_GP_on
-    is_HANGUL_ED_utf8_safe
-    is_HORIZWS_cp_high
-    is_HORIZWS_high
     isIDCONT_LC_utf8
     isIDFIRST_lazy_if_safe
     isIDFIRST_LC_utf8
-    is_LARGER_NON_CHARS_utf8
     is_LAX_VERSION
     isLEXWARN_off
     isLEXWARN_on
-    is_LNBREAK_latin1_safe
-    is_LNBREAK_safe
-    is_LNBREAK_utf8_safe
     isLOWER_LC_utf8
-    is_MULTI_CHAR_FOLD_latin1_safe
-    is_MULTI_CHAR_FOLD_utf8_safe
-    is_NONCHAR_utf8_safe
     IS_NUMERIC_RADIX
-    is_PATWS_safe
     is_posix_ALPHA
     is_posix_ALPHANUMERIC
     is_posix_ASCII
@@ -886,23 +874,10 @@ my %unresolved_visibility_overrides = map { $_ => 1 } qw(
     is_posix_WORDCHAR
     is_posix_XDIGIT
     isPRINT_LC_utf8
-    is_PROBLEMATIC_LOCALE_FOLD_cp
-    is_PROBLEMATIC_LOCALE_FOLDEDS_START_cp
-    is_PROBLEMATIC_LOCALE_FOLDEDS_START_utf8
-    is_PROBLEMATIC_LOCALE_FOLD_utf8
     isPSXSPC_LC_utf8
     isPUNCT_LC_utf8
-    is_QUOTEMETA_high
-    is_SHORTER_NON_CHARS_utf8
     isSPACE_LC_utf8
-    is_SPACE_utf8_safe_backwards
     is_STRICT_VERSION
-    is_SURROGATE_utf8
-    is_SURROGATE_utf8_safe
-    is_THREE_CHAR_FOLD_HEAD_latin1_safe
-    is_THREE_CHAR_FOLD_HEAD_utf8_safe
-    is_THREE_CHAR_FOLD_latin1_safe
-    is_THREE_CHAR_FOLD_utf8_safe
     isU8_ALPHA_LC
     isU8_ALPHANUMERIC_LC
     isU8_ASCII_LC
@@ -921,19 +896,13 @@ my %unresolved_visibility_overrides = map { $_ => 1 } qw(
     isU8_XDIGIT_LC
     isUNICODE_POSSIBLY_PROBLEMATIC
     isUPPER_LC_utf8
-    is_VERTWS_cp_high
-    is_VERTWS_high
     isVERTWS_utf8
     isWARNf_on
     isWARN_on
     isWARN_ONCE
     isWORDCHAR_lazy_if_safe
     isWORDCHAR_LC_utf8
-    is_XDIGIT_cp_high
-    is_XDIGIT_high
     isXDIGIT_LC_utf8
-    is_XPERLSPACE_cp_high
-    is_XPERLSPACE_high
     IV_MAX_P1
     JE_OLD_STACK_HWM_restore
     JE_OLD_STACK_HWM_save
@@ -2117,8 +2086,6 @@ my %unresolved_visibility_overrides = map { $_ => 1 } qw(
     WARN_NONEstring
     WARNshift
     WARNsize
-    what_MULTI_CHAR_FOLD_latin1_safe
-    what_MULTI_CHAR_FOLD_utf8_safe
     WIN32SCK_IS_STDSCK
     withinCOUNT
     WORTH_PER_WORD_LOOP
diff --git a/regen/regcharclass.pl b/regen/regcharclass.pl
index 5a1839246e..103fdbd977 100755
--- a/regen/regcharclass.pl
+++ b/regen/regcharclass.pl
@@ -6,6 +6,7 @@ use warnings;
 use warnings FATAL => 'all';
 use Data::Dumper;
 $Data::Dumper::Useqq= 1;
+use charnames qw();

 sub DEBUG () { 0 }
 $|=1 if DEBUG;
@@ -400,6 +401,7 @@ my %n2a;        # Inversion of a2n, for each character set
 my %I8_2_utf;
 my %utf_2_I8;   # Inversion of I8_2_utf, for each EBCDIC character set
 my @identity = (0..255);
+my %seen;       # Only display items in this hash once

 sub new {
     my $class= shift;
@@ -413,6 +415,8 @@ sub new {
     my $self= bless {
         op    => $opt{op},
         title => $opt{title} || '',
+        overview => $opt{overview} || '',
+        charcount => $opt{charcount} || 1,
     }, $class;

     my $charset = $opt{charset};
@@ -1468,7 +1472,7 @@ sub render {
 }

 # make_macro
-# make a macro of a given type.
+# make a macro and its pod of a given type.
 # calls into make_trie and (generic_|length_)optree as needed
 # Opts are:
 # type             : 'cp', 'cp_high', 'generic', 'high', 'low', 'latin1',
@@ -1508,6 +1512,7 @@ sub make_macro {
         }
     }
     my $ret_type= $opts{ret_type} || ( $opts{type} =~ /^cp/ ? 'cp' : 'len' );
+    my $returns_cp = $ret_type eq 'cp';
     my $method;
     if ( $opts{safe} ) {
         $method= 'length_optree';
@@ -1516,10 +1521,159 @@ sub make_macro {
     } else {
         $method= 'optree';
     }
-    my @args= $type =~ /^cp/ ? 'cp' : 's';
-    push @args, "e" if $opts{safe};
-    push @args, "is_utf8" if $type =~ /generic/;
-    push @args, "len" if $ret_type eq 'both';
+
+    my $title = $self->{title};
+    my $overview = $self->{overview};
+    my $charcount = $self->{charcount};
+
+    my @args;
+    my $doc_arglist = "";
+    my $doc_text = "";
+
+    # Autogenerate an apidoc entry for this macro based on what we can glean
+    # from the inputs.  This turns out to do a decent job of it.
+    my $range = $type =~ /low/ ? "ASCII-range"
+              : $type =~ /high/ ? "above-Latin1 range"
+              : $type =~ /latin1/i ? "Latin1-range"
+              : "";
+
+    my $character;      # What spelling of 'character we are to use'
+    if ($charcount > 1) {
+        $character = 'character sequence';
+    }
+    else {
+
+        # 'strs' contains the byte or UTF-8 of each thing matched by this
+        # macro.  Choose one, and see if it has a name.  If not, such as for a
+        # surrogate, we use the term 'code point';
+        my @matches = sort keys $self->{strs}->%*;
+        $character = ( ! @matches
+                      || defined charnames::viacode(ord $matches[0]))
+                    ? 'character' : 'code point';
+    }
+
+    # $overview comes from <DATA>, and is optional.  Use it if furnished, as
+    # it is intended to be documentation.  It will be written so 'such a'
+    # makes sense.
+    my $matched;
+    if ($overview ne "") {
+        $doc_text = $overview . "\n";
+        $matched = "such a $character";
+        if ($range ne "") {
+            $matched .= " that is";
+            $matched .= " entirely" if $charcount > 1;
+            $matched .= " in the $range";
+        }
+    }
+    else {  # No $overview.  Fall back to using the (mandatory) title
+        $matched = "a $range";
+        $matched .= " " if $range ne "";
+        $matched .= "$character that matches $self->{title}";
+    }
+
+    my $otherwise = "Otherwise, it returns zero.\n";
+
+    if ($type =~ /^cp/) {
+        $args[0] = 'cp';
+        $doc_arglist .= "|UV cp";
+        $doc_text .= <<~EOT;
+            This returns non-zero if code point C<cp> is
+            $matched.
+
+            $otherwise
+            EOT
+    }
+    else {  # The input is a string
+        $args[0] = 's';     # The first agrument is always named 's'
+        $doc_arglist .= "|const U8 * s";
+
+        my $back = "";
+        my $sign = '-';
+        if ($opts{backwards}) {
+            $back = "BACK ";
+            $sign = '+';
+        }
+
+        my $sequence_bytes_description;
+        if ($opts{safe}) {
+            push @args, "e";
+            $doc_arglist .= "|const U8 * e";
+            $sequence_bytes_description =
+                "sequence of bytes starting at C<s>, and extending no further"
+              . " ${back}than S<C<e> $sign 1>";
+        }
+        else {
+            $sequence_bytes_description =
+                            "sequence of the next few bytes starting at C<s>";
+        }
+
+        if ($returns_cp) {
+            $doc_text .= <<~EOT;
+                This returns the code point that the input byte(s) form if
+                they match $matched.
+
+                It returns zero otherwise.  Fortunately C<NUL> is not matched
+                by this, or else disambiguation would be required.
+                EOT
+
+                # It's a bit presumptuous to assume that NUL will never be
+                # matched by some new macro coming along, but it is quite
+                # unlikely given that these macros are generally for very
+                # complicated things.
+        }
+        elsif ($type =~ /generic/) {
+            $doc_text .= <<~EOT;
+                This returns non-zero if the input byte(s) form $matched.
+
+                If C<is_utf8> is C<false>, the input is considered to be
+                Latin1, and the single byte at C<*s> is examined.
+
+                If C<is_utf8> is C<true>, the input is considered to be UTF-8,
+                and the
+                $sequence_bytes_description
+                are examined.
+                EOT
+        }
+        else {
+            $doc_text .= <<~EOT;
+                This returns non-zero if the
+                $sequence_bytes_description
+                form a valid UTF-8 representation of $matched.
+                EOT
+        }
+
+        $doc_text .= <<~EOT;
+
+        $otherwise
+        The value returned gives the number of bytes the matched
+        $character actually occupies.
+        EOT
+
+        if (! $opts{safe} && $type !~ /^cp/) {
+            $doc_text .= <<~EOT;
+
+                You need to be sure that the bytes at C<s> comprise at least
+                one complete $character before calling this; otherwise this
+                could read beyond its end.
+                EOT
+        }
+    }
+
+    # Fix any grammar problem of this sort coming from the result of
+    # concatenation
+    $doc_text =~ s/ \b a \  ([aeiou]) /an $1/gx;
+
+    if ($type =~ /generic/) {
+        push @args, "is_utf8";
+        $doc_arglist .= "|bool is_utf8";
+    }
+
+     if ($ret_type eq 'both') {
+        push @args, "len";
+        $doc_arglist .= "|STRLEN len";
+        warn "Generating apidoc for -both is currently unimplemented";
+    }
+
     my $pfx= $ret_type eq 'both'    ? 'what_len_' :
              $ret_type eq 'cp'      ? 'what_'     : 'is_';
     my $ext= $type     =~ /generic/ ? ''          : '_' . lc( $type );
@@ -1531,7 +1685,11 @@ sub make_macro {
     my $macro = "$pfx$self->{op}$ext";
     my $def_fmt="$macro%s($argstr)";
     my $optree= $self->$method( %opts, type => $type, ret_type => $ret_type );
-    return $self->render( $optree, ($type =~ /^cp/) ? 1 : 0, \%opts, $def_fmt );
+    my $api_ret = ($returns_cp) ? 'UV' : 'STRLEN';
+    my $pod = "=for apidoc CT|$api_ret|$macro$doc_arglist\n$doc_text";
+
+    return $self->render( $optree, ($type =~ /^cp/) ? 1 : 0, \%opts, $def_fmt ),
+           $pod;
 }

 # if we aren't being used as a module (highly likely) then process
@@ -1558,12 +1716,16 @@ EOF
     );

     print $out_fh <<~EOT;
+        /*
+        =for apidoc_section \$classification
+        */

         #ifndef PERL_REGCHARCLASS_H_ /* Guard against nested #includes */
         #  define PERL_REGCHARCLASS_H_

         EOT
-    my ( $op, $title, @txt, @types, %mods );
+
+    my ( $op, $title, @txt, @types, %mods, $overview, $charcount);
     my $doit= sub ($) {
         return unless $op;

@@ -1574,9 +1736,14 @@ EOF
         return if delete $mods{only_ebcdic_platform} && $charset !~ /ebcdic/i;

         print $out_fh "/*\n\t$op: $title for $charset\n\n";
+
         print $out_fh join "\n", ( map { "\t$_" } @txt ), "*/", "";
-        my $obj= __PACKAGE__->new( op => $op, title => $title, txt => \@txt,
-                                                        charset => $charset);
+        my $obj= __PACKAGE__->new( op => $op,
+                                   title => $title,
+                                   txt => \@txt,
+                                   overview => $overview,
+                                   charcount => $charcount,
+                                   charset => $charset);

         #die Dumper(\@types,\%mods);

@@ -1610,7 +1777,7 @@ EOF
                         && ($mod eq 'safe' || $mod eq 'no_length_checks')
                         && grep { 'fast' =~ $_ } @mods;
                 delete $mods{$mod};
-                my $macro= $obj->make_macro(
+                my ($macro, $api) = $obj->make_macro(
                     type     => $type,
                     ret_type => $ret,
                     safe     => $mod eq 'safe' && $type !~ /^cp/,
@@ -1619,6 +1786,20 @@ EOF
                                      && $type !~ /^cp/,
                     backwards => $backwards,
                 );
+
+                my $first_line = $api =~ s/\n.*//rs;
+
+                if (! $seen{$first_line}++) {
+                    print $out_fh <<~EOT;
+                        /*
+                        $api
+
+                        =cut
+                        */
+
+                        EOT
+                }
+
                 print $out_fh $macro, "\n";
             }
         }
@@ -1633,6 +1814,9 @@ EOF
         undef @txt;
         undef @types;
         undef %mods;
+        undef $overview;
+        undef $charcount;
+
         print $out_fh "\n", get_conditional_compile_line_start($charset);
         for (my $i = 0; $i < @data; $i++) {
             my $line = $data[$i];
@@ -1648,13 +1832,16 @@ EOF

                 $first_time = 0;
                 ( $op, my $flags, $title )= split /\s*:\s*/, $line, 3;
+                $charcount = ($flags =~ s/(\d)//)
+                             ? $1
+                             : 1;

                 @txt= ();
                 $title =~ s/ \s* \# .* //x;

                 # Now get the optional overview, which is all subsequent lines
                 # up to the marker that begins the definition.
-                my $overview = "";
+                $overview = "";
                 while ($i < @data - 1) {
                     last if $data[$i+1] =~ $definition_begin_re;
                     $i++;
@@ -1717,7 +1904,9 @@ EOF
 # value given by 'BASE'.  The rest of the names are described in the pod of
 # this file.
 #
-# 'flags' are currently ignored.
+# Only the numeric values of 'flags' are currently used.
+# These are '1', '2', or '3'.  They give the maximum
+# number of characters the macro can match.  If omitted, '1' is assumed.
 #
 # Finally is 'title' which is output in comments associated with the macro
 # that are its title or description.
@@ -1732,7 +1921,9 @@ EOF
 # those lines begins with a scalar symbol, the code will replace the
 # scalar with its contents.  This allows you to set up variables in the
 # program and then refer to them in these lines.  The impetus would be to
-# easily share text between multiple macros.
+# easily share text between multiple macros.  The overview is used to create
+# a documentation entry for this macro.  See the existing examples for how
+# this works.
 #
 # The '=>' line contains those two characters followed by the types of
 # macro(s) to be generated; these are specified below.  A colon follows the
@@ -1944,6 +2135,8 @@ LARGER_NON_CHARS: e :   # 5 bytes
 # Note that code in utf8.c is counting on the 'fast' version to look at no
 # more than two bytes
 SURROGATE: C : Surrogate code points
+Surrogate code points enable UTF-16 to be extended to be able to represent all
+Unicode code points
 => UTF8 :safe fast
 \p{_Perl_Surrogate}

diff --git a/t/porting/symbol_visibility.dat b/t/porting/symbol_visibility.dat
index 88638b8963..19838ffee0 100644
--- a/t/porting/symbol_visibility.dat
+++ b/t/porting/symbol_visibility.dat
@@ -1 +1 @@
-44585
+43635