mirror/perl
1
0
Fork 0
mirror of https://github.com/Perl/perl5.git synced 2026-01-26 08:38:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

perlapi: Improve wording of plain/nocontext entries

Browse Source 
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.
This commit is contained in:
Karl Williamson 2025-09-22 21:12:50 -06:00 committed by Karl Williamson
parent 1ccc2b0b89
commit 658039d704
5 changed files with 31 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
autodoc.pl
View File

@ -84,22 +84,17 @@ my $irrelevant_flags_re = qr/[ ab eE iI P rR X? ]/xx;
# apidoc_item # apidoc_item
my $item_flags_re = qr/[dD fF mM nN oO pT uU Wx;]/xx; 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. # Certain functions have plain and no_context versions, and meet the criteria
my @have_compatibility_macros = qw( # stated here. Each of their pods has been modified to have a marker line
deb # which this program replaces by this wording. This way we can tweak the
form # wording in one place, and still have it placed in the individual pod entries
load_module # where it makes the most sense.
mess my $PLAIN_vs_NOCONTEXT_wording = <<~EOT;
newSVpvf C<WHICH> and C<WHICH_nocontext> behave identically when called from outside
sv_catpvf the perl core unless C<PERL_WANT_VARARGS> has been explicitly #defined.
sv_catpvf_mg When it has, or when called from inside the core, they differ only in that
sv_setpvf C<WHICH> requires the thread context (C<aTHX>) to be available.
sv_setpvf_mg EOT
warn
warner
);
my %has_compat_macro;
$has_compat_macro{$_} = 1 for @have_compatibility_macros;
use constant { use constant {
NOT_APIDOC => -1, NOT_APIDOC => -1,
@ -1665,7 +1660,6 @@ sub docout ($fh, $section_name, $element_name, $docref) {
my @deprecated; my @deprecated;
my @experimental; my @experimental;
my @xrefs; my @xrefs;
my @compat_macros;
for (my $i = 0; $i < @items; $i++) { for (my $i = 0; $i < @items; $i++) {
last if $docref->{'xref_only'}; # Place holder 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 @deprecated, "C<$name>" if $item->{flags} =~ /D/;
push @experimental, "C<$name>" if $item->{flags} =~ /x/; 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 # 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 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"; print $fh "\n", $pod, "\n";
# Accumulate the usage section of the entry into this array. Output below # 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<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) { if (grep { /\S/ } @usage) {
print $fh "\n=over $usage_indent\n\n"; print $fh "\n=over $usage_indent\n\n";
print $fh join "", @usage; print $fh join "", @usage;

4
deb.c
View File

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

4
op.c
View File

@ -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 If C<PERL_LOADMOD_DENY> is set, the module is loaded as if with C<no> rather
than C<use>. than C<use>.
C<load_module> and C<load_module_nocontext> have the same apparent signature, __PLAIN_vs_NOCONTEXT_wording__(load_module)
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>.
=for apidoc Amnh||PERL_LOADMOD_DENY =for apidoc Amnh||PERL_LOADMOD_DENY
=for apidoc Amnh||PERL_LOADMOD_NOIMPORT =for apidoc Amnh||PERL_LOADMOD_NOIMPORT

13
sv.c
View File

@ -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 These each create a new SV and initialize it with the string formatted like
C<sv_catpvf>. C<sv_catpvf>.
__PLAIN_vs_NOCONTEXT_wording__(newSVpvf)
=for apidoc vnewSVpvf =for apidoc vnewSVpvf
Like C<L</newSVpvf>> but the arguments are a C<va_list>. 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 extensions to the standard set of %formats can override this (see
L<perlguts/Formatted Printing of Strings> and adjacent sections). L<perlguts/Formatted Printing of Strings> and adjacent sections).
The forms whose name contains C<_no_context> do not take a thread __PLAIN_vs_NOCONTEXT_wording__(sv_setpvf)
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_mg)
The forms whose name contains C<vset> use a C<va_list>, the The forms whose name contains C<vset> use a C<va_list>, the
other forms use C<sprintf>-style arguments. 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 extensions to the standard set of %formats can override this (see
L<perlguts/Formatted Printing of Strings> and adjacent sections). L<perlguts/Formatted Printing of Strings> and adjacent sections).
The forms whose name contains C<_no_context> do not take a thread __PLAIN_vs_NOCONTEXT_wording__(sv_catpvf)
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_mg)
The forms whose name contains C<vcat> use a C<va_list>, the The forms whose name contains C<vcat> use a C<va_list>, the
other forms use C<sprintf>-style arguments. other forms use C<sprintf>-style arguments.

17
util.c
View File

@ -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 that the return was a single per-thread buffer. That was (and is) actually
true only when these are called during global destruction. true only when these are called during global destruction.
C<form> and C<form_nocontext> differ only in that C<form_nocontext> does __PLAIN_vs_NOCONTEXT_wording__(form)
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.
C<vform> is the same as C<form> except the arguments are a C<va_list>. 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 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 then it will be extended with some indication of the current location in the
code, as described for C<L</mess_sv>>. code, as described for C<L</mess_sv>>.
C<mess> and C<mess_nocontext> differ only in that C<mess_nocontext> does __PLAIN_vs_NOCONTEXT_wording__(mess)
not take a thread context (C<aTHX>) parameter, so is used in situations where
the caller doesn't already have the thread context.
C<vmess> is the same as C<mess> except the arguments are a <va_list>. 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 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. 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 __PLAIN_vs_NOCONTEXT_wording__(warn)
context (C<aTHX>) parameter, so is used in situations where the caller doesn't
already have the thread context.
=cut =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. C<pat> is not permitted to be null.
The two forms differ only in that C<warner_nocontext> does not take a thread __PLAIN_vs_NOCONTEXT_wording__(warner)
context (C<aTHX>) parameter, so is used in situations where the caller doesn't
already have the thread context.
These functions differ from the similarly named C<L</warn>> functions, in that 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 the latter are for XS code to unconditionally display a warning, whereas these