diff --git a/autodoc.pl b/autodoc.pl index 4347cc62d898..51f718877ffe 100644 --- a/autodoc.pl +++ b/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 and C behave identically when called from outside + the perl core unless C has been explicitly #defined. + When it has, or when called from inside the core, they differ only in that + C requires the thread context (C) 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 unless C has - been C<#defined>, in which case it expands to - C. When called from the perl core, - it assumes C is available, so expands to - C - EOT - } - if (grep { /\S/ } @usage) { print $fh "\n=over $usage_indent\n\n"; print $fh join "", @usage; diff --git a/deb.c b/deb.c index 20814e3c276b..4db8523f40ae 100644 --- a/deb.c +++ b/deb.c @@ -53,9 +53,7 @@ the script causing the call, and the line number within that file. If the C (verbose) debugging option is in effect, the process id is also printed. -C and C differ only in that C does not take -a thread context (C) parameter, so is used in situations where the caller -doesn't already have the thread context. +__PLAIN_vs_NOCONTEXT_wording__(deb) C is the same as C except C is a pointer to a C. diff --git a/op.c b/op.c index 4e5a63f1eefd..903fa6ad9f16 100644 --- a/op.c +++ b/op.c @@ -8495,9 +8495,7 @@ decremented. In addition, the C argument is modified. If C is set, the module is loaded as if with C rather than C. -C and C 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. +__PLAIN_vs_NOCONTEXT_wording__(load_module) =for apidoc Amnh||PERL_LOADMOD_DENY =for apidoc Amnh||PERL_LOADMOD_NOIMPORT diff --git a/sv.c b/sv.c index 79d670cd69bf..dd94430d06c2 100644 --- a/sv.c +++ b/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. -=for apidoc newSVpvf_nocontext -Like C> but does not take a thread context (C) 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> but the arguments are a C. @@ -11629,9 +11627,9 @@ to be the same UTF8ness as the destination C, though certain Perl extensions to the standard set of %formats can override this (see L and adjacent sections). -The forms whose name contains C<_no_context> do not take a thread -context (C) 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 use a C, the other forms use C-style arguments. @@ -11788,9 +11786,9 @@ to be the same UTF8ness as the destination C, though certain Perl extensions to the standard set of %formats can override this (see L and adjacent sections). -The forms whose name contains C<_no_context> do not take a thread -context (C) 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 use a C, the other forms use C-style arguments. diff --git a/util.c b/util.c index 5e64975ed777..1f38b5b1150f 100644 --- a/util.c +++ b/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
and C differ only in that C does -not take a thread context (C) parameter, so is used in situations where -the caller doesn't already have the thread context (and can be called without -the C prefix. +__PLAIN_vs_NOCONTEXT_wording__(form) C is the same as C except the arguments are a C. 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>. -C and C differ only in that C does -not take a thread context (C) parameter, so is used in situations where -the caller doesn't already have the thread context. +__PLAIN_vs_NOCONTEXT_wording__(mess) C is the same as C except the arguments are a . 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>, C is not permitted to be null. -The two forms differ only in that C does not take a thread -context (C) 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 is not permitted to be null. -The two forms differ only in that C does not take a thread -context (C) 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> functions, in that the latter are for XS code to unconditionally display a warning, whereas these