From b00fe9dd8f54ac0de283562ae4f2e360e6239a54 Mon Sep 17 00:00:00 2001
From: Karl Williamson <khw@cpan.org>
Date: Sun, 30 Jun 2024 14:31:06 -0600
Subject: [PATCH] perlapi: Combine all forms of pad_findmy()

---
 pad.c | 54 +++++++++++++++++++++++++++++-------------------------
 pad.h |  5 +----
 2 files changed, 30 insertions(+), 29 deletions(-)

diff --git a/pad.c b/pad.c
index ee9af633092c..4ad101f2b022 100644
--- a/pad.c
+++ b/pad.c
@@ -939,16 +939,38 @@ S_pad_check_dup(pTHX_ PADNAME *name, U32 flags, const HV *ourstash)
 
 
 /*
-=for apidoc pad_findmy_pvn
+=for apidoc      pad_findmy_pv
+=for apidoc_item pad_findmy_pvn
+=for apidoc_item pad_findmy_pvs
+=for apidoc_item pad_findmy_sv
+
+Given the name of a lexical variable, including its leading sigil, find its
+position in the currently-compiling pad.
 
-Given the name of a lexical variable, find its position in the
-currently-compiling pad.
-C<namepv>/C<namelen> specify the variable's name, including leading sigil.
-C<flags> is reserved and must be zero.
 If it is not in the current pad but appears in the pad of any lexically
 enclosing scope, then a pseudo-entry for it is added in the current pad.
-Returns the offset in the current pad,
-or C<NOT_IN_PAD> if no such lexical is in scope.
+
+These each return the offset in the current pad, or C<NOT_IN_PAD> if no such
+lexical is in scope.
+
+The forms differ only in how the variable's name is specified.
+
+In C<pad_findmy_pvs>, the variable name is a C language string literal,
+enclosed in double quotes.
+
+In plain C<pad_findmy_pv>, the variable name is a C language NUL-terminated
+string.
+
+In C<pad_findmy_pvn>, C<len> gives the length of the variable name in bytes,
+so it may contain embedded-NUL characters.  The caller must make sure C<namepv>
+contains at least C<len> bytes.
+
+In C<pad_findmy_sv>, the variable name is taken from the SV parameter using
+C<L</SvPVutf8>()>.
+
+C<flags> is reserved and must be zero.
+
+=for apidoc Amnh||NOT_IN_PAD
 
 =cut
 */
@@ -1001,15 +1023,6 @@ Perl_pad_findmy_pvn(pTHX_ const char *namepv, STRLEN namelen, U32 flags)
     return NOT_IN_PAD;
 }
 
-/*
-=for apidoc pad_findmy_pv
-
-Exactly like L</pad_findmy_pvn>, but takes a nul-terminated string
-instead of a string/length pair.
-
-=cut
-*/
-
 PADOFFSET
 Perl_pad_findmy_pv(pTHX_ const char *name, U32 flags)
 {
@@ -1017,15 +1030,6 @@ Perl_pad_findmy_pv(pTHX_ const char *name, U32 flags)
     return pad_findmy_pvn(name, strlen(name), flags);
 }
 
-/*
-=for apidoc pad_findmy_sv
-
-Exactly like L</pad_findmy_pvn>, but takes the name string in the form
-of an SV instead of a string/length pair.
-
-=cut
-*/
-
 PADOFFSET
 Perl_pad_findmy_sv(pTHX_ SV *name, U32 flags)
 {
diff --git a/pad.h b/pad.h
index 049c48005e88..0877aa6c3124 100644
--- a/pad.h
+++ b/pad.h
@@ -542,10 +542,7 @@ instead of a string/length pair.
     Perl_pad_add_name_pvn(aTHX_ STR_WITH_LEN(name), flags, typestash, ourstash)
 
 /*
-=for apidoc Am|PADOFFSET|pad_findmy_pvs|"name"|U32 flags
-
-Exactly like L</pad_findmy_pvn>, but takes a literal string
-instead of a string/length pair.
+=for apidoc_defn Am|PADOFFSET|pad_findmy_pvs|"name"|U32 flags
 
 =cut
 */