[svn:parrot] r42090 - trunk/docs

[allison at svn.parrot.org]

Author: allison
Date: Sun Oct 25 15:42:37 2009
New Revision: 42090
URL: https://trac.parrot.org/parrot/changeset/42090

Log:
[cage] Note the deprecated functions for calling subs/methods in the API
documentation, and document the replacement function.

Modified:
   trunk/docs/embed.pod

Modified: trunk/docs/embed.pod
==============================================================================
--- trunk/docs/embed.pod	Sun Oct 25 15:40:59 2009	(r42089)
+++ trunk/docs/embed.pod	Sun Oct 25 15:42:37 2009	(r42090)
@@ -348,15 +348,21 @@
 
 =over 4
 
-=item C<void *Parrot_call_sub(PARROT_INTERP, Parrot_PMC sub, const_char *signature)>
+=item C<void Parrot_ext_call(PARROT_INTERP, Parrot_PMC sub, const_char *signature, varargs ...)>
+
+Call a Parrot subroutine using the supplied signature. Variables to be filled
+with return values are passed as references in the varargs list, after all
+arguments.
+
+=item [DEPRECATED] C<void *Parrot_call_sub(PARROT_INTERP, Parrot_PMC sub, const_char *signature)>
 
 Call a Parrot subroutine that returns a pointer using the supplied signature.
 
-=item C<Parrot_Int Parrot_call_sub_ret_int(PARROT_INTERP, Parrot_PMC sub, const_char *signature)>
+=item [DEPRECATED] C<Parrot_Int Parrot_call_sub_ret_int(PARROT_INTERP, Parrot_PMC sub, const_char *signature)>
 
 Call a Parrot subroutine that returns an integer using the supplied signature.
 
-=item C<Parrot_Float Parrot_call_sub_ret_float(PARROT_INTERP, Parrot_PMC sub, const_char *signature)>
+=item [DEPRECATED] C<Parrot_Float Parrot_call_sub_ret_float(PARROT_INTERP, Parrot_PMC sub, const_char *signature)>
 
 Call a Parrot subroutine that returns an float using the supplied signature.
 
@@ -383,7 +389,15 @@
 
 =head3 Calling methods
 
-Not documented yet.
+=over 4
+
+=item C<void Parrot_ext_call(PARROT_INTERP, Parrot_PMC method, const_char *signature, varargs ...)>
+
+Methods are called using the same API function as calling a subroutine. The
+first argument should be the object that the method will be invoked on, and it
+should have the signature "Pi".
+
+=back
 
 =head1 COMPILING
 
@@ -589,17 +603,19 @@
 
 =item C<Parrot_callback_D>
 
-=item C<Parrot_call_method>
+=item C<Parrot_ext_call>
+
+=item [DEPRECATED] C<Parrot_call_method>
 
-=item C<Parrot_call_method_ret_float>
+=item [DEPRECATED] C<Parrot_call_method_ret_float>
 
-=item C<Parrot_call_method_ret_int>
+=item [DEPRECATED] C<Parrot_call_method_ret_int>
 
-=item C<Parrot_call_sub>
+=item [DEPRECATED] C<Parrot_call_sub>
 
-=item C<Parrot_call_sub_ret_float>
+=item [DEPRECATED] C<Parrot_call_sub_ret_float>
 
-=item C<Parrot_call_sub_ret_int>
+=item [DEPRECATED] C<Parrot_call_sub_ret_int>
 
 =item C<Parrot_char_digit_value>