From: Doug MacEachern <dougm@covalent.net>
Date: Tue, 12 Jun 2001 22:04:50 +0000 (-0700)
Subject: Re: ext/ + -Wall
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=9f2ea79885dcd731e16cfe839c551021222566a9;p=p5sagit%2Fp5-mst-13.2.git

Re: ext/ + -Wall
Message-ID: <Pine.LNX.4.21.0106122151180.24181-100000@mako.covalent.net>

Document ax and break up dXSARGS.

p4raw-id: //depot/perl@10558
---

diff --git a/XSUB.h b/XSUB.h
index 13c5ea9..acc0cde 100644
--- a/XSUB.h
+++ b/XSUB.h
@@ -18,6 +18,11 @@ Variable which is setup by C<xsubpp> to designate the object in a C++
 XSUB.  This is always the proper type for the C++ object.  See C<CLASS> and 
 L<perlxs/"Using XS With C++">.
 
+=for apidoc Amn|I32|ax
+Variable which is setup by C<xsubpp> to indicate the stack base offset,
+used by the C<ST>, C<XSprePUSH> and C<XSRETURN> macros.  The C<dMARK> macro
+must be called prior to setup the C<MARK> variable.
+
 =for apidoc Amn|I32|items
 Variable which is setup by C<xsubpp> to indicate the number of 
 items on the stack.  See L<perlxs/"Variable-length Parameter Lists">.
@@ -33,10 +38,18 @@ Used to access elements on the XSUB's stack.
 Macro to declare an XSUB and its C parameter list.  This is handled by
 C<xsubpp>.
 
+=for apidoc Ams||dAX
+Sets up the C<ax> variable.
+This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
+
+=for apidoc Ams||dITEMS
+Sets up the C<items> variable.
+This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
+
 =for apidoc Ams||dXSARGS
-Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.  This
-is usually handled automatically by C<xsubpp>.  Declares the C<items>
-variable to indicate the number of items on the stack.
+Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
+Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>.
+This is usually handled automatically by C<xsubpp>.
 
 =for apidoc Ams||dXSI32
 Sets up the C<ix> variable for an XSUB which has aliases.  This is usually
@@ -56,10 +69,13 @@ handled automatically by C<xsubpp>.
 /* gcc -Wall: if an xsub has no arguments and PPCODE is used
  * and none of ST, XSRETURN or XSprePUSH macros are used
  * then `ax' (setup by dXSARGS) is unused. */
+#define dAX I32 ax __attribute__((unused)) = MARK - PL_stack_base + 1
+
+#define dITEMS I32 items = SP - MARK
+
 #define dXSARGS				\
 	dSP; dMARK;			\
-	I32 ax __attribute__((unused)) = mark - PL_stack_base + 1;	\
-	I32 items = sp - mark
+	dAX; dITEMS
 
 #define dXSTARG SV * targ = ((PL_op->op_private & OPpENTERSUB_HASTARG) \
 			     ? PAD_SV(PL_op->op_targ) : sv_newmortal())
diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index 84e2dc7..d67da13 100644
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -182,6 +182,17 @@ must then use C<av_store> to assign values to these new elements.
 =for hackers
 Found in file av.c
 
+=item ax
+
+Variable which is setup by C<xsubpp> to indicate the stack base offset,
+used by the C<ST>, C<XSprePUSH> and C<XSRETURN> macros.  The C<dMARK> macro
+must be called prior to setup the C<MARK> variable.
+
+	I32	ax
+
+=for hackers
+Found in file XSUB.h
+
 =item bytes_from_utf8
 
 Converts a string C<s> of length C<len> from UTF8 into byte encoding.
@@ -320,6 +331,26 @@ L<perlsub/"Constant Functions">.
 =for hackers
 Found in file op.c
 
+=item dAX
+
+Sets up the C<ax> variable.
+This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
+
+		dAX;
+
+=for hackers
+Found in file XSUB.h
+
+=item dITEMS
+
+Sets up the C<items> variable.
+This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
+
+		dITEMS;
+
+=for hackers
+Found in file XSUB.h
+
 =item dMARK
 
 Declare a stack marker variable, C<mark>, for the XSUB.  See C<MARK> and
@@ -351,9 +382,9 @@ Found in file pp.h
 
 =item dXSARGS
 
-Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.  This
-is usually handled automatically by C<xsubpp>.  Declares the C<items>
-variable to indicate the number of items on the stack.
+Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
+Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>.
+This is usually handled automatically by C<xsubpp>.
 
 		dXSARGS;
 
@@ -2430,19 +2461,19 @@ false, defined or undefined.  Does not handle 'get' magic.
 =for hackers
 Found in file sv.h
 
-=item SvTYPE
-
-Returns the type of the SV.  See C<svtype>.
+=item svtype
 
-	svtype	SvTYPE(SV* sv)
+An enum of flags for Perl types.  These are found in the file B<sv.h> 
+in the C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
 
 =for hackers
 Found in file sv.h
 
-=item svtype
+=item SvTYPE
 
-An enum of flags for Perl types.  These are found in the file B<sv.h> 
-in the C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
+Returns the type of the SV.  See C<svtype>.
+
+	svtype	SvTYPE(SV* sv)
 
 =for hackers
 Found in file sv.h