From 2228b3d92dc6b04915a758fc6d3e4d724fb976c7 Mon Sep 17 00:00:00 2001
From: Karl Williamson <khw@cpan.org>
Date: Sat, 5 Sep 2020 21:31:27 -0600
Subject: [PATCH] perlapi: Consolidate sv_catsv-ish entries

---
 mathoms.c |  8 --------
 sv.c      | 31 ++++++++++++++++++++-----------
 sv.h      |  2 --
 3 files changed, 20 insertions(+), 21 deletions(-)

diff --git a/mathoms.c b/mathoms.c
index 332c57e..a07b260 100644
--- a/mathoms.c
+++ b/mathoms.c
@@ -283,14 +283,6 @@ Perl_sv_catsv(pTHX_ SV *dsv, SV *sstr)
     sv_catsv_flags(dsv, sstr, SV_GMAGIC);
 }
 
-/*
-=for apidoc sv_catsv_mg
-
-Like C<sv_catsv>, but also handles 'set' magic.
-
-=cut
-*/
-
 void
 Perl_sv_catsv_mg(pTHX_ SV *dsv, SV *sstr)
 {
diff --git a/sv.c b/sv.c
index b5e3a72..4e9f45a 100644
--- a/sv.c
+++ b/sv.c
@@ -5516,20 +5516,29 @@ Perl_sv_catpvn_flags(pTHX_ SV *const dsv, const char *sstr, const STRLEN slen, c
 
 /*
 =for apidoc sv_catsv
+=for apidoc_item sv_catsv_flags
+=for apidoc_item sv_catsv_mg
+=for apidoc_item sv_catsv_nomg
 
-Concatenates the string from SV C<ssv> onto the end of the string in SV
-C<dsv>.  If C<ssv> is null, does nothing; otherwise modifies only C<dsv>.
-Handles 'get' magic on both SVs, but no 'set' magic.  See C<L</sv_catsv_mg>>
-and C<L</sv_catsv_nomg>>.
+These concatenate the string from SV C<sstr> onto the end of the string in SV
+C<dsv>.  If C<sstr> is null, these are no-ops; otherwise only C<dsv> is
+modified.
 
-=for apidoc sv_catsv_flags
+They differ only in what magic they perform:
 
-Concatenates the string from SV C<ssv> onto the end of the string in SV
-C<dsv>.  If C<ssv> is null, does nothing; otherwise modifies only C<dsv>.
-If C<flags> has the C<SV_GMAGIC> bit set, will call C<L</mg_get>> on both SVs if
-appropriate.  If C<flags> has the C<SV_SMAGIC> bit set, C<L</mg_set>> will be called on
-the modified SV afterward, if appropriate.  C<sv_catsv>, C<sv_catsv_nomg>,
-and C<sv_catsv_mg> are implemented in terms of this function.
+C<sv_catsv_mg> performs 'get' magic on both SVs before the copy, and 'set' magic
+on C<dsv> afterwards.
+
+C<sv_catsv> performs just 'get' magic, on both SVs.
+
+C<sv_catsv_nomg> skips all magic.
+
+C<sv_catsv_flags> has an extra C<flags> parameter which allows you to use
+C<SV_GMAGIC> and/or C<SV_SMAGIC> to specify any combination of magic handling
+(although either both or neither SV will have 'get' magic applied to it.)
+
+C<sv_catsv>, C<sv_catsv_mg>, and C<sv_catsv_nomg> are implemented
+in terms of C<sv_catsv_flags>.
 
 =cut */
 
diff --git a/sv.h b/sv.h
index bf4885b..fc35f34 100644
--- a/sv.h
+++ b/sv.h
@@ -1720,8 +1720,6 @@ scalar.
 =for apidoc Am|void|sv_catpv_nomg|SV* sv|const char* ptr
 Like C<sv_catpv> but doesn't process magic.
 
-=for apidoc Am|void|sv_catsv_nomg|SV* dsv|SV* ssv
-Like C<sv_catsv> but doesn't process magic.
 =cut
 */
 
-- 
1.8.3.1