[PATCH] perlapi.pod Enhancements

Hi all,

This is a patch to enhance perlapi.pod by providing Perl equivalents and
clarifying documentation where appropriate.

It can also be found as a series of git commits here:

https://github.com/shlomif/perl/tree/shlomif-xs-doc

Comments are welcome.

Regards,

-- Shlomi Fish

diff --git a/av.c b/av.c
index 9dd4a76..eabe495 100644
--- a/av.c
+++ b/av.c
@@ -275,11 +275,15 @@ Perl_av_fetch(pTHX_ register AV *av, I32 key, I32 lval)
 Stores an SV in an array.  The array index is specified as C<key>.  The
 return value will be NULL if the operation failed or if the value did not
 need to be actually stored within the array (as in the case of tied
-arrays). Otherwise it can be dereferenced to get the original C<SV*>.  Note
-that the caller is responsible for suitably incrementing the reference
+arrays). Otherwise, it can be dereferenced to get the C<SV*> that was stored
+there (= C<val>)).
+
+Note that the caller is responsible for suitably incrementing the reference
 count of C<val> before the call, and decrementing it if the function
 returned NULL.
 
+Perl equivalent: C<$myarray[$key] = $val;>.
+
 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
 more information on how to use this function on tied arrays.
 
@@ -529,6 +533,8 @@ Perl_av_create_and_push(pTHX_ AV **const avp, SV *const val)
 Pushes an SV onto the end of the array.  The array will grow automatically
 to accommodate the addition. This takes ownership of one reference count.
 
+Perl equivalent: C<push @myarray, $elem;>.
+
 =cut
 */
 
@@ -558,6 +564,8 @@ Perl_av_push(pTHX_ register AV *av, SV *val)
 Pops an SV off the end of the array.  Returns C<&PL_sv_undef> if the array
 is empty.
 
+Perl equivalent: C<my $elem = pop(@myarray);>
+
 =cut
 */
 
@@ -617,6 +625,8 @@ Unshift the given number of C<undef> values onto the
beginning of the array.  The array will grow automatically to accommodate the
addition.  You must then use C<av_store> to assign values to these new elements.
 
+Perl equivalent: C<unshift @myarray, ( (undef()) x $n );>
+    
 =cut
 */
 
@@ -679,6 +689,8 @@ Perl_av_unshift(pTHX_ register AV *av, register I32 num)
 Shifts an SV off the beginning of the array. Returns C<&PL_sv_undef> if the 
 array is empty.
 
+Perl equivalent: C<my $elem = shift(@myarray);>
+
 =cut
 */
 
diff --git a/av.h b/av.h
index 5231c4d..0f8a87e 100644
--- a/av.h
+++ b/av.h
@@ -83,6 +83,8 @@ Same as C<av_len()>.  Deprecated, use C<av_len()> instead.
 
 Creates a new AV.  The reference count is set to 1.
 
+Perl equivalent: C<sub newAV { return []; }>.
+
 =cut
 */
 
diff --git a/cv.h b/cv.h
index 6fdf5cb..87d9853 100644
--- a/cv.h
+++ b/cv.h
@@ -26,8 +26,13 @@ Null CV pointer.
 
 =head1 CV Manipulation Functions
 
+This section documents functions to manipulate CVs which are code-values,
+containing subroutine references. For more information, see L<perlguts> .
+
 =for apidoc Am|HV*|CvSTASH|CV* cv
-Returns the stash of the CV.
+Returns the stash of the CV. A stash is the symbol table hash, containing
+the package-scope variables in the package where the subroutine was defined.
+For more information, see L<perlguts>.
 
 =cut
 */
diff --git a/perl.c b/perl.c
index 914fbcd..bd32362 100644
--- a/perl.c
+++ b/perl.c
@@ -2388,11 +2388,23 @@ Perl_get_sv(pTHX_ const char *name, I32 flags)
 
 =for apidoc p||get_av
 
-Returns the AV of the specified Perl array.  C<flags> are passed to
-C<gv_fetchpv>. If C<GV_ADD> is set and the
+Returns the AV of the specified Perl package-scope array with the given name
+(so it won't work on lexical variables).  C<flags> are passed 
+to C<gv_fetchpv>. If C<GV_ADD> is set and the
 Perl variable does not exist then it will be created.  If C<flags> is zero
 and the variable does not exist then NULL is returned.
 
+Perl equivalent:
+
+    sub get_array_by_name
+    {
+	my ($name) = @_;
+
+	no strict 'refs';
+
+	return \@{$name};
+    }
+
 =cut
 */
 
@@ -2494,7 +2506,19 @@ Perl_get_cv(pTHX_ const char *name, I32 flags)
 
 =for apidoc p||call_argv
 
-Performs a callback to the specified Perl sub.  See L<perlcall>.
+Performs a callback to the specified named and package-scope Perl subroutine 
+with C<argv> (a NULL-terminated array of strings) as arguments. See
L<perlcall>. +
+Perl equivalent:
+
+    sub call_argv
+    {
+        my ($sub_name, @$argv) = @_;
+
+        not strict 'refs';
+
+        return &{$sub_name}(@$argv);
+    }
 
 =cut
 */


-- 
-----------------------------------------------------------------
Shlomi Fish       http://www.shlomifish.org/
"Humanity" - Parody of Modern Life - http://shlom.in/humanity

Larry Wall has been changing the world. By modifying its very source code.

Please reply to list if it's a mailing list post - http://shlom.in/reply .

• [PATCH] perlapi.pod Enhancements by Shlomi Fish
• Re: [PATCH] perlapi.pod Enhancements by Father Chrysostomos
• Re: [PATCH] perlapi.pod Enhancements by Shlomi Fish
• Re: [PATCH] perlapi.pod Enhancements by Father Chrysostomos
• Re: [PATCH] perlapi.pod Enhancements by Dave Mitchell
• Re: [PATCH] perlapi.pod Enhancements by Shlomi Fish
• Re: [PATCH] perlapi.pod Enhancements by Dave Mitchell
• Deferred ops in the peephole optimizer and user-defined rpeep by Vincent Pit
• Re: Deferred ops in the peephole optimizer and user-defined rpeep by Dave Mitchell