perlapi: Improve wording of plain/nocontext entries

Certain functions have forms that contain the suffix '_nocontext', and
which have long been specially handled in embed.h.  autodoc was unaware
of these until 14c379e recently.

This tweaks the wording added in that commit, and by changing to use an
in-line marker where its desired in the pod instead of an arbitrary
place dictated from above, makes the result flow better.

Author: khwilliamson

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

@@ -10434,6 +10434,7 @@ Perl_newSVpvf_nocontext(const char *const pat, ...)
 These each create a new SV and initialize it with the string formatted like
 C<sv_catpvf>.
 
+__PLAIN_vs_NOCONTEXT_wording__(newSVpvf)
 
 =for apidoc vnewSVpvf
 Like C<L</newSVpvf>> but the arguments are a C<va_list>.
@@ -11626,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.
@@ -11785,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