From 658039d704d3e7395a6b1e324fd032668b81dd7b Mon Sep 17 00:00:00 2001 From: Karl Williamson Date: Mon, 22 Sep 2025 21:12:50 -0600 Subject: [PATCH] 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 14c379ecac400409463db8546c137ce9b92bcf1d 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. --- autodoc.pl | 48 ++++++++++++++++++------------------------------ deb.c | 4 +--- op.c | 4 +--- sv.c | 13 +++++++------ util.c | 17 ++++------------- 5 files changed, 31 insertions(+), 55 deletions(-) diff --git a/autodoc.pl b/autodoc.pl index 4347cc62d8..51f718877f 100644 --- a/autodoc.pl +++ b/autodoc.pl @@ -84,22 +84,17 @@ my $irrelevant_flags_re = qr/[ ab eE iI P rR X? ]/xx; # 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 @@ sub docout ($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 @@ sub docout ($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 @@ sub docout ($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 @@ sub docout ($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 20814e3c27..4db8523f40 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 4e5a63f1ee..903fa6ad9f 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 c23eb40aa2..dd94430d06 100644 --- a/sv.c +++ b/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. +__PLAIN_vs_NOCONTEXT_wording__(newSVpvf) =for apidoc vnewSVpvf Like C> but the arguments are a C. @@ -11626,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. @@ -11785,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 5e64975ed7..1f38b5b115 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