perlapi: Improve wording of plain/nocontext entries

autodoc.pl

@@ -84,22 +84,17 @@
 # apidoc_item
 my $item_flags_re = qr/[dD fF mM nN oO pT uU Wx;]/xx;
 
-# This is a copy of the list in regen/embed.pl.
-my @have_compatibility_macros = qw(
-                                    deb
-                                    form
-                                    load_module
-                                    mess
-                                    newSVpvf
-                                    sv_catpvf
-                                    sv_catpvf_mg
-                                    sv_setpvf
-                                    sv_setpvf_mg
-                                    warn
-                                    warner
-                                  );
-my %has_compat_macro;
-$has_compat_macro{$_} = 1 for @have_compatibility_macros;
+# 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
+# wording in one place, and still have it placed in the individual pod entries
+# where it makes the most sense.
+my $PLAIN_vs_NOCONTEXT_wording = <<~EOT;
+    C<WHICH> and C<WHICH_nocontext> behave identically when called from outside
+    the perl core unless C<PERL_WANT_VARARGS> has been explicitly #defined.
+    When it has, or when called from inside the core, they differ only in that
+    C<WHICH> requires the thread context (C<aTHX>) to be available.
+    EOT
 
 use constant {
               NOT_APIDOC         => -1,
@@ -1665,7 +1660,6 @@ ($fh, $section_name, $element_name, $docref)
     my @deprecated;
     my @experimental;
     my @xrefs;
-    my @compat_macros;
 
     for (my $i = 0; $i < @items; $i++) {
         last if $docref->{'xref_only'}; # Place holder
@@ -1682,7 +1676,6 @@ ($fh, $section_name, $element_name, $docref)
 
             push @deprecated,   "C<$name>" if $item->{flags} =~ /D/;
             push @experimental, "C<$name>" if $item->{flags} =~ /x/;
-            push @compat_macros, $name if $has_compat_macro{$name};
         }
 
         # While we're going though the items, construct a nice list of where
@@ -1780,6 +1773,13 @@ ($fh, $section_name, $element_name, $docref)
     }
 
     chomp $pod;     # Make sure prints pod with a single trailing \n
+
+    # Replace this marker line in the pod with what we say it should expand
+    # to.
+    $pod =~ s{ \b __PLAIN_vs_NOCONTEXT_wording__ \( (\w+) \) }{
+        my $this = $1;
+        $PLAIN_vs_NOCONTEXT_wording =~ s/WHICH/$this/gr
+    }xeg;
     print $fh "\n", $pod, "\n";
 
     # Accumulate the usage section of the entry into this array.  Output below
@@ -2186,18 +2186,6 @@ ($fh, $section_name, $element_name, $docref)
         }
     }
 
-    for my $compat (@compat_macros) {
-        print $fh <<~"EOT";
-
-            Note: When called from XS code, $compat(...) expands to
-            C<Perl_${compat}_no_context(...)> unless C<PERL_WANT_VARARGS> has
-            been C<#defined>, in which case it expands to
-            C<Perl_$compat(aTHX_ ...)>.  When called from the perl core,
-            it assumes C<aTHX> is available, so expands to
-            C<Perl_$compat(aTHX_ ...)>
-            EOT
-    }
-
     if (grep { /\S/ } @usage) {
         print $fh "\n=over $usage_indent\n\n";
         print $fh join "", @usage;

deb.c

@@ -53,9 +53,7 @@ the script causing the call, and the line number within that file.
 If the C<v> (verbose) debugging option is in effect, the process id is also
 printed.
 
-C<deb> and C<deb_nocontext> differ only in that C<deb_nocontext> does not take
-a thread context (C<aTHX>) parameter, so is used in situations where the caller
-doesn't already have the thread context.
+__PLAIN_vs_NOCONTEXT_wording__(deb)
 
 C<vdeb> is the same as C<deb> except C<args> is a pointer to a C<va_list>.
 

op.c

@@ -8495,9 +8495,7 @@ 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>.
 
-C<load_module> and C<load_module_nocontext> have the same apparent signature,
-but the former hides the fact that it is accessing a thread context parameter.
-So use the latter when you get a compilation error about C<pTHX>.
+__PLAIN_vs_NOCONTEXT_wording__(load_module)
 
 =for apidoc Amnh||PERL_LOADMOD_DENY
 =for apidoc Amnh||PERL_LOADMOD_NOIMPORT

sv.c

@@ -10428,15 +10428,13 @@ Perl_newSVpvf_nocontext(const char *const pat, ...)
 #endif
 
 /*
-=for apidoc newSVpvf
+=for apidoc      newSVpvf
+=for apidoc_item newSVpvf_nocontext
 
-Creates a new SV and initializes it with the string formatted like
+These each create a new SV and initialize it with the string formatted like
 C<sv_catpvf>.
 
-=for apidoc newSVpvf_nocontext
-Like C<L</newSVpvf>> but does not take a thread context (C<aTHX>) parameter,
-so is used in situations where the caller doesn't already have the thread
-context.
+__PLAIN_vs_NOCONTEXT_wording__(newSVpvf)
 
 =for apidoc vnewSVpvf
 Like C<L</newSVpvf>> but the arguments are a C<va_list>.
@@ -11629,9 +11627,9 @@ to be the same UTF8ness as the destination C<sv>, though certain Perl
 extensions to the standard set of %formats can override this  (see
 L<perlguts/Formatted Printing of Strings> and adjacent sections).
 
-The forms whose name contains C<_no_context> do not take a thread
-context (C<aTHX>) parameter, so are used in situations where the caller
-doesn't already have the thread context.
+__PLAIN_vs_NOCONTEXT_wording__(sv_setpvf)
+
+__PLAIN_vs_NOCONTEXT_wording__(sv_setpvf_mg)
 
 The forms whose name contains C<vset> use a C<va_list>, the
 other forms use C<sprintf>-style arguments.
@@ -11788,9 +11786,9 @@ to be the same UTF8ness as the destination C<sv>, though certain Perl
 extensions to the standard set of %formats can override this  (see
 L<perlguts/Formatted Printing of Strings> and adjacent sections).
 
-The forms whose name contains C<_no_context> do not take a thread
-context (C<aTHX>) parameter, so are used in situations where the caller
-doesn't already have the thread context.
+__PLAIN_vs_NOCONTEXT_wording__(sv_catpvf)
+
+__PLAIN_vs_NOCONTEXT_wording__(sv_catpvf_mg)
 
 The forms whose name contains C<vcat> use a C<va_list>, the
 other forms use C<sprintf>-style arguments.

util.c

@@ -1434,10 +1434,7 @@ This is contrary to the incorrect previous documentation of these that claimed
 that the return was a single per-thread buffer.  That was (and is) actually
 true only when these are called during global destruction.
 
-C<form> and C<form_nocontext> differ only in that C<form_nocontext> does
-not take a thread context (C<aTHX>) parameter, so is used in situations where
-the caller doesn't already have the thread context (and can be called without
-the C<Perl_> prefix.
+__PLAIN_vs_NOCONTEXT_wording__(form)
 
 C<vform> is the same as C<form> except the arguments are a C<va_list>.
 It does need a thread context parameter, but that is supplied
@@ -1477,9 +1474,7 @@ used to generate a string message.  If the message does not end with a newline,
 then it will be extended with some indication of the current location in the
 code, as described for C<L</mess_sv>>.
 
-C<mess> and C<mess_nocontext> differ only in that C<mess_nocontext> does
-not take a thread context (C<aTHX>) parameter, so is used in situations where
-the caller doesn't already have the thread context.
+__PLAIN_vs_NOCONTEXT_wording__(mess)
 
 C<vmess> is the same as C<mess> except the arguments are a <va_list>.
 It needs a thread context parameter only when called with the
@@ -2018,9 +2013,7 @@ but this is subject to modification by a C<$SIG{__WARN__}> handler.
 
 Unlike with C<L</croak>>, C<pat> is not permitted to be null.
 
-The two forms differ only in that C<warn_nocontext> does not take a thread
-context (C<aTHX>) parameter, so is used in situations where the caller doesn't
-already have the thread context.
+__PLAIN_vs_NOCONTEXT_wording__(warn)
 
 =cut
 */
@@ -2069,9 +2062,7 @@ but this is subject to modification by a C<$SIG{__WARN__}> handler.
 
 C<pat> is not permitted to be null.
 
-The two forms differ only in that C<warner_nocontext> does not take a thread
-context (C<aTHX>) parameter, so is used in situations where the caller doesn't
-already have the thread context.
+__PLAIN_vs_NOCONTEXT_wording__(warner)
 
 These functions differ from the similarly named C<L</warn>> functions, in that
 the latter are for XS code to unconditionally display a warning, whereas these