From f651c04aa9df4e58f4a76f30dafe4023e6fe0940 Mon Sep 17 00:00:00 2001
From: Karl Williamson <khw@cpan.org>
Date: Fri, 21 Jun 2024 13:18:27 -0600
Subject: [PATCH] perlapi: Fold in gv_autoload4 to gv_autoload_pv group

And correct some of the misleading documentation previously there
---
 embed.fnc |  4 ----
 gv.c      | 31 ++++++++++++++++++++++++-------
 gv.h      |  8 ++++----
 proto.h   |  4 ----
 4 files changed, 28 insertions(+), 19 deletions(-)

diff --git a/embed.fnc b/embed.fnc
index fd2e02f20cdb..73892bf84a3e 100644
--- a/embed.fnc
+++ b/embed.fnc
@@ -1291,10 +1291,6 @@ Adp	|GV *	|gv_add_by_type |NULLOK GV *gv				\
 				|svtype type
 Adp	|int	|Gv_AMupdate	|NN HV *stash				\
 				|bool destructing
-ARdm	|GV *	|gv_autoload4	|NULLOK HV *stash			\
-				|NN const char *name			\
-				|STRLEN len				\
-				|I32 method
 ARdp	|GV *	|gv_autoload_pv |NULLOK HV *stash			\
 				|NN const char *namepv			\
 				|U32 flags
diff --git a/gv.c b/gv.c
index 6bd190b6b49a..3e98c0aac68e 100644
--- a/gv.c
+++ b/gv.c
@@ -1296,34 +1296,51 @@ Perl_gv_fetchmethod_pvn_flags(pTHX_ HV *stash, const char *name, const STRLEN le
     return gv;
 }
 
-
 /*
 =for apidoc      gv_autoload_pv
 =for apidoc_item gv_autoload_pvn
 =for apidoc_item gv_autoload_sv
+=for apidoc_item gv_autoload4
 
 These each search for an C<AUTOLOAD> method, returning NULL if not found, or
 else returning a pointer to its GV, while setting the package
-L<C<$AUTOLOAD>|perlobj/AUTOLOAD> variable to C<name> (fully qualified).  Also,
-if found and the GV's CV is an XSUB, the CV's PV will be set to C<name>, and
+L<C<$AUTOLOAD>|perlobj/AUTOLOAD> variable to the name (fully qualified).  Also,
+if found and the GV's CV is an XSUB, the CV's PV will be set to the name, and
 its stash will be set to the stash of the GV.
 
 Searching is done in L<C<MRO> order|perlmroapi>, as specified in
 L</C<gv_fetchmeth>>, beginning with C<stash> if it isn't NULL.
 
-The forms differ only in how C<name> is specified.
+C<gv_autoload4>) has a C<method> parameter; the others a C<flags> one  (both
+types explained below).  Otherwise, the forms differ only in how the name is
+specified.
 
 In C<gv_autoload_pv>, C<namepv> is a C language NUL-terminated string.
 
-In C<gv_autoload_pvn>, C<name> points to the first byte of the name, and an
-additional parameter, C<len>, specifies its length in bytes.  Hence, C<*name>
-may contain embedded-NUL characters.
+In C<gv_autoload_pvn> and C<gv_autoload4>), C<name> points to the first byte of
+the name, and an additional parameter, C<len>, specifies its length in bytes.
+Hence, C<*name> may contain embedded-NUL characters.
 
 In C<gv_autoload_sv>, C<*namesv> is an SV, and the name is the PV extracted
 from that using L</C<SvPV>>.  If the SV is marked as being in UTF-8, the
 extracted PV will also be.
 
+The other way to indicate that the name is encoded as UTF-8 is to set the 
+C<SVf_UTF8> bit in C<flags> for the forms that have that parameter.  
+The name is never considered to be UTF-8 in C<gv_autoload4>.
+
+The C<method> parameter in C<gv_autoload4> is used only to indicate that the
+name is for a method (non-zero), or not (zero).  The other forms use the
+C<GV_AUTOLOAD_ISMETHOD> bit in C<flags> to indicate this.
+
+The only other significant value in C<flags> currently is C<GV_SUPER>
+to indicate, if set, to skip searching for the name in C<stash>.
+
 =cut
+
+=for apidoc Amnh||GV_AUTOLOAD_ISMETHOD
+=for apidoc Amnh||SVf_UTF8
+=for apidoc Amnh||GV_SUPER
 */
 
 GV*
diff --git a/gv.h b/gv.h
index 2de17674c09f..1dd38b43d04c 100644
--- a/gv.h
+++ b/gv.h
@@ -262,7 +262,8 @@ Return the CV from the GV.
 #define GV_NOUNIVERSAL  0x2000  /* Skip UNIVERSAL lookup */
 
 /* Flags for gv_autoload_*/
-#define GV_AUTOLOAD_ISMETHOD 1	/* autoloading a method? */
+#define GV_AUTOLOAD_ISMETHOD 1	/* autoloading a method?  gv_autoload4 will
+                                   break if this is changed from being 1 */
 
 /*      SVf_UTF8 (more accurately the return value from SvUTF8) is also valid
         as a flag to various gv_* functions, so ensure it lies
@@ -289,10 +290,9 @@ Return the CV from the GV.
 #define gv_fetchmethod_flags(stash,name,flags) gv_fetchmethod_pv_flags(stash, name, flags)
 
 /*
-=for apidoc gv_autoload4
-Equivalent to C<L</gv_autoload_pvn>>.
-
+=for apidoc_defn ARdp|GV *|gv_autoload4|NULLOK HV *stash|NN const char *name|STRLEN len|I32 method
 =cut
+
 */
 #define gv_autoload4(stash, name, len, autoload) \
         gv_autoload_pvn(stash, name, len, cBOOL(autoload))
diff --git a/proto.h b/proto.h
index 089abb1934ed..c6930fda4c13 100644
--- a/proto.h
+++ b/proto.h
@@ -1358,10 +1358,6 @@ PERL_CALLCONV GV *
 Perl_gv_add_by_type(pTHX_ GV *gv, svtype type);
 #define PERL_ARGS_ASSERT_GV_ADD_BY_TYPE
 
-/* PERL_CALLCONV GV *
-gv_autoload4(pTHX_ HV *stash, const char *name, STRLEN len, I32 method)
-        __attribute__warn_unused_result__; */
-
 PERL_CALLCONV GV *
 Perl_gv_autoload_pv(pTHX_ HV *stash, const char *namepv, U32 flags)
         __attribute__warn_unused_result__;