This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Consolidate and document all get_cvFOO() variants
authorKarl Williamson <khw@cpan.org>
Wed, 22 Jul 2020 22:47:53 +0000 (16:47 -0600)
committerKarl Williamson <khw@cpan.org>
Sun, 13 Dec 2020 23:27:17 +0000 (16:27 -0700)
perl.c

diff --git a/perl.c b/perl.c
index 3c97ed5..6c3ed0d 100644 (file)
--- a/perl.c
+++ b/perl.c
@@ -2831,17 +2831,24 @@ Perl_get_hv(pTHX_ const char *name, I32 flags)
 /*
 =for apidoc_section $CV
 
-=for apidoc get_cvn_flags
+=for apidoc get_cv
+=for apidoc_item |CV *|get_cvs|"string"|I32 flags
+=for apidoc_item get_cvn_flags
 
-Returns the CV of the specified Perl subroutine.  C<flags> are passed to
+These return the CV of the specified Perl subroutine.  C<flags> are passed to
 C<gv_fetchpvn_flags>.  If C<GV_ADD> is set and the Perl subroutine does not
 exist then it will be declared (which has the same effect as saying
-C<sub name;>).  If C<GV_ADD> is not set and the subroutine does not exist
+C<sub name;>).  If C<GV_ADD> is not set and the subroutine does not exist,
 then NULL is returned.
 
-=for apidoc get_cv
+The forms differ only in how the subroutine is specified..  With C<get_cvs>,
+the name is a literal C string, enclosed in double quotes.  With C<get_cv>, the
+name is given by the C<name> parameter, which must be a NUL-terminated C
+string.  With C<get_cvn_flags>, the name is also given by the C<name>
+parameter, but it is a Perl string (possibly containing embedded NUL bytes),
+and its length in bytes is contained in the C<len> parameter.
 
-Uses C<strlen> to get the length of C<name>, then calls C<get_cvn_flags>.
+=for apidoc Amnh||GV_ADD
 
 =cut
 */