perlapi: Combine all forms of sv_derived_from into one group

universal.c

@@ -123,20 +123,33 @@ S_sv_derived_from_svpvn(pTHX_ SV *sv, SV *namesv, const char * name, const STRLE
 /*
 =for apidoc_section $SV
 
-=for apidoc sv_derived_from_pvn
+=for apidoc      sv_derived_from
+=for apidoc_item sv_derived_from_hv
+=for apidoc_item sv_derived_from_pv
+=for apidoc_item sv_derived_from_pvn
+=for apidoc_item sv_derived_from_sv
 
-Returns a boolean indicating whether the SV is derived from the specified class
-I<at the C level>.  To check derivation at the Perl level, call C<isa()> as a
-normal Perl method.
+These each return a boolean indicating whether C<sv> is derived from the
+specified class I<at the C level>.  To check derivation at the Perl level, call
+C<isa()> as a normal Perl method.
 
-Currently, the only significant value for C<flags> is SVf_UTF8.
+In C<sv_derived_from_hv>, the class name is C<HvNAME(hv)> (which would
+presumably represent a stash).  Its UTF8ness is C<HvNAMEUTF8(hv)>.
 
-=cut
+In C<sv_derived_from> and C<sv_derived_from_pv>, the class name is given by
+C<name>, which is a NUL-terminated C string.  In C<sv_derived_from>, the name
+is never considered to be encoded as UTF-8.
+
+The remaining forms differ only in how the class name is specified;
+they all have a C<flags> parameter. Currently, the only significant value for
+which is C<SVf_UTF8> to indicate that the class name is encoded as such.
 
-=for apidoc sv_derived_from_sv
+In C<sv_derived_from_sv>, the class name is extracted from C<namesv>.
+This is the preferred form.  The class name is considered to be in UTF-8 if
+C<namesv> is marked as such.
 
-Exactly like L</sv_derived_from_pvn>, but takes the name string in the form
-of an SV instead of a string/length pair. This is the advised form.
+In C<sv_derived_from_pvn>, C<len> gives the length of C<name>, so the latter
+may contain embedded NUL characters.
 
 =cut
 
@@ -149,30 +162,13 @@ Perl_sv_derived_from_sv(pTHX_ SV *sv, SV *namesv, U32 flags)
     return sv_derived_from_svpvn(sv, namesv, NULL, 0, flags);
 }
 
-/*
-=for apidoc sv_derived_from
-
-Exactly like L</sv_derived_from_pv>, but doesn't take a C<flags> parameter.
-
-=cut
-*/
-
 bool
 Perl_sv_derived_from(pTHX_ SV *sv, const char *const name)
 {
     PERL_ARGS_ASSERT_SV_DERIVED_FROM;
     return sv_derived_from_svpvn(sv, NULL, name, strlen(name), 0);
 }
 
-/*
-=for apidoc sv_derived_from_pv
-
-Exactly like L</sv_derived_from_pvn>, but takes a nul-terminated string 
-instead of a string/length pair.
-
-=cut
-*/
-
 
 bool
 Perl_sv_derived_from_pv(pTHX_ SV *sv, const char *const name, U32 flags)
@@ -188,15 +184,6 @@ Perl_sv_derived_from_pvn(pTHX_ SV *sv, const char *const name, const STRLEN len,
     return sv_derived_from_svpvn(sv, NULL, name, len, flags);
 }
 
-/*
-=for apidoc sv_derived_from_hv
-
-Exactly like L</sv_derived_from_pvn>, but takes the name string as the
-C<HvNAME> of the given HV (which would presumably represent a stash).
-
-=cut
-*/
-
 bool
 Perl_sv_derived_from_hv(pTHX_ SV *sv, HV *hv)
 {