perlapi: Combine all forms of savepv into one group

Having one group containing the descriptions of all closely related
functions makes the pod more compact and makes maintenance easier; fixes
only need to be applied in one place.  And it encourages the
documentation authors to compare and contrast the variants, paying
closer attention to the subtle differences between them.

And it is easier for the reader to choose the variant that is best for
their current purpose, rather than hopping around the file, unsure if
the current text is identical to that found elsewhere, or if there is a
subtle nuance (or three).

handy.h

@@ -407,16 +407,6 @@ string/length pair.
 Like C<sv_setref_pvn>, but takes a literal string instead of
 a string/length pair.
 
-=for apidoc_section $string
-
-=for apidoc Ama|char*|savepvs|"literal string"
-Like C<savepvn>, but takes a literal string instead of a
-string/length pair.
-
-=for apidoc Ama|char*|savesharedpvs|"literal string"
-A version of C<savepvs()> which allocates the duplicate string in memory
-which is shared between threads.
-
 =for apidoc_section $GV
 
 =for apidoc Am|HV*|gv_stashpvs|"name"|I32 create
@@ -468,8 +458,15 @@ Perl_xxx(aTHX_ ...) form for any API calls where it's used.
 #define sv_setpvs_mg(sv, str) Perl_sv_setpvn_mg(aTHX_ sv, STR_WITH_LEN(str))
 #define sv_setref_pvs(rv, classname, str) \
     Perl_sv_setref_pvn(aTHX_ rv, classname, STR_WITH_LEN(str))
+
+/*
+=for apidoc_defn Ama|char*|savepvs|"literal string"
+=for apidoc_defn Ama|char*|savesharedpvs|"literal string"
+=cut
+*/
 #define savepvs(str) Perl_savepvn(aTHX_ STR_WITH_LEN(str))
 #define savesharedpvs(str) Perl_savesharedpvn(aTHX_ STR_WITH_LEN(str))
+
 #define gv_stashpvs(str, create) \
     Perl_gv_stashpvn(aTHX_ STR_WITH_LEN(str), create)
 

inline.h

@@ -4416,19 +4416,49 @@ Perl_padnamelist_refcnt_inc(PADNAMELIST *pnl)
 
 /*
 =for apidoc_section $string
-=for apidoc savepv
+=for apidoc      savepv
+=for apidoc_item savepvn
+=for apidoc_item savepvs
+=for apidoc_item savesvpv
+=for apidoc_item savesharedpv
+=for apidoc_item savesharedpvn
+=for apidoc_item savesharedpvs
+=for apidoc_item savesharedsvpv
 
-Perl's version of C<strdup()>.  Returns a pointer to a newly allocated
-string which is a duplicate of C<pv>.  The size of the string is
-determined by C<strlen()>, which means it may not contain embedded C<NUL>
-characters and must have a trailing C<NUL>.  To prevent memory leaks, the
-memory allocated for the new string needs to be freed when no longer needed.
-This can be done with the C<L</Safefree>> function, or
-L<C<SAVEFREEPV>|perlguts/SAVEFREEPV(p)>.
+Perl's version of C<strdup()> (or C<strndup()> would be if it existed).
 
-On some platforms, Windows for example, all allocated memory owned by a thread
-is deallocated when that thread ends.  So if you need that not to happen, you
-need to use the shared memory functions, such as C<L</savesharedpv>>.
+These each return a pointer to a newly allocated string which is a duplicate of
+the input string.
+
+The forms differ in how the string to be copied is specified, and where the new
+memory is allocated from.
+
+To prevent memory leaks, the memory allocated for the new string needs to be
+freed when no longer needed.  This can be done with the C<L</Safefree>>
+function, or L<C<SAVEFREEPV>|perlguts/SAVEFREEPV(p)>.
+
+The forms whose names contain C<shared> differ from the corresponding form
+without that in its name, only in that the memory in the former comes from
+memory shared between threads.  This is needed, because on some platforms,
+Windows for example, all allocated memory owned by a thread is deallocated when
+that thread ends.  So if you need that not to happen, you need to use the
+shared memory forms.
+
+The string to copy in C<savepvs> is a C language string literal surrounded by
+double quotes.
+
+The string to copy in the forms whose name contains C<svpv> comes from the PV
+in the SV argument C<sv>, using C<SvPV()>
+
+The string to copy in the remaining forms comes from the C<pv> argument.
+
+In the case of C<savepv>, the size of the string is determined by C<strlen()>,
+which means it may not contain embedded C<NUL> characters, and must have a
+trailing C<NUL>.
+
+In the case of C<savepvn>, C<len> gives the length of C<pv>, hence it may
+contain embedded C<NUL> characters.  The copy will be guaranteed to have a
+trailing NUL added if not already present.
 
 =cut
 */
@@ -4449,22 +4479,6 @@ Perl_savepv(pTHX_ const char *pv)
 
 /* same thing but with a known length */
 
-/*
-=for apidoc savepvn
-
-Perl's version of what C<strndup()> would be if it existed.  Returns a
-pointer to a newly allocated string which is a duplicate of the first
-C<len> bytes from C<pv>, plus a trailing
-C<NUL> byte.  The memory allocated for
-the new string can be freed with the C<Safefree()> function.
-
-On some platforms, Windows for example, all allocated memory owned by a thread
-is deallocated when that thread ends.  So if you need that not to happen, you
-need to use the shared memory functions, such as C<L</savesharedpvn>>.
-
-=cut
-*/
-
 PERL_STATIC_INLINE char *
 Perl_savepvn(pTHX_ const char *pv, Size_t len)
 {
@@ -4483,19 +4497,6 @@ Perl_savepvn(pTHX_ const char *pv, Size_t len)
     }
 }
 
-/*
-=for apidoc savesvpv
-
-A version of C<savepv()>/C<savepvn()> which gets the string to duplicate from
-the passed in SV using C<SvPV()>
-
-On some platforms, Windows for example, all allocated memory owned by a thread
-is deallocated when that thread ends.  So if you need that not to happen, you
-need to use the shared memory functions, such as C<L</savesharedsvpv>>.
-
-=cut
-*/
-
 PERL_STATIC_INLINE char *
 Perl_savesvpv(pTHX_ SV *sv)
 {
@@ -4510,15 +4511,6 @@ Perl_savesvpv(pTHX_ SV *sv)
     return (char *) CopyD(pv,newaddr,len,char);
 }
 
-/*
-=for apidoc savesharedsvpv
-
-A version of C<savesharedpv()> which allocates the duplicate string in
-memory which is shared between threads.
-
-=cut
-*/
-
 PERL_STATIC_INLINE char *
 Perl_savesharedsvpv(pTHX_ SV *sv)
 {

util.c

@@ -1320,14 +1320,6 @@ Perl_cntrl_to_mnemonic(const U8 c)
     return NULL;
 }
 
-/*
-=for apidoc savesharedpv
-
-A version of C<savepv()> which allocates the duplicate string in memory
-which is shared between threads.
-
-=cut
-*/
 char *
 Perl_savesharedpv(pTHX_ const char *pv)
 {
@@ -1347,15 +1339,6 @@ Perl_savesharedpv(pTHX_ const char *pv)
     return (char*)memcpy(newaddr, pv, pvlen);
 }
 
-/*
-=for apidoc savesharedpvn
-
-A version of C<savepvn()> which allocates the duplicate string in memory
-which is shared between threads.  (With the specific difference that a C<NULL>
-pointer is not acceptable)
-
-=cut
-*/
 char *
 Perl_savesharedpvn(pTHX_ const char *const pv, const STRLEN len)
 {