From e70aab199a3555c2e19966af5137fb8c99676337 Mon Sep 17 00:00:00 2001
From: "James E. Keenan" <jkeenan@cpan.org>
Date: Wed, 14 Apr 2010 22:21:27 -0400
Subject: [PATCH] Add documentation on the hashrefs produced by
 process_typemaps().

---
 .../lib/ExtUtils/ParseXS/Utilities.pm              | 80 +++++++++++++++++++++-
 1 file changed, 79 insertions(+), 1 deletion(-)

diff --git a/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS/Utilities.pm b/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS/Utilities.pm
index b25df02..16494d3 100644
--- a/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS/Utilities.pm
+++ b/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS/Utilities.pm
@@ -40,7 +40,17 @@ ExtUtils::ParseXS::Utilities - Subroutines used with ExtUtils::ParseXS
     C_string
     valid_proto_string
     process_typemaps
+    process_single_typemap
     make_targetable
+    map_type
+    standard_XS_defs
+    assign_func_args
+    analyze_preprocessor_statements
+    set_cond
+    Warn
+    blurt
+    death
+    check_conditional_preprocessor_statements
   );
 
 =head1 SUBROUTINES
@@ -278,7 +288,75 @@ directory.
 =item * Return Value
 
 Upon success, returns a list of four hash references.  (This will probably be
-refactored.)
+refactored.)  Here is a I<rough> description of what is in these hashrefs:
+
+=over 4
+
+=item * C<$type_kind_ref>
+
+  {
+    'char **' => 'T_PACKEDARRAY',
+    'bool_t' => 'T_IV',
+    'AV *' => 'T_AVREF',
+    'InputStream' => 'T_IN',
+    'double' => 'T_DOUBLE',
+    # ...
+  }
+
+Keys:  C types.  Values:  Corresponding Perl types.
+
+=item * C<$proto_letter_ref>
+
+  {
+    'char **' => '$',
+    'bool_t' => '$',
+    'AV *' => '$',
+    'InputStream' => '$',
+    'double' => '$',
+    # ...
+  }
+
+Keys: C types.  Values. Corresponding prototype letters.
+
+=item * C<$input_expr_ref>
+
+  {
+    'T_CALLBACK' => '	$var = make_perl_cb_$type($arg)
+  ',
+    'T_OUT' => '	$var = IoOFP(sv_2io($arg))
+  ',
+    'T_REF_IV_PTR' => '	if (sv_isa($arg, \\"${ntype}\\")) {
+    # ...
+  }
+
+Keys:  Perl API calls B<CONFIRM!>.  Values:  Newline-terminated strings that
+will be written to C source code (F<.c>) files.   The strings are C code, but
+with Perl variables whose values will be interpolated at F<xsubpp>'s runtime
+by one of the C<eval EXPR> statements in ExtUtils::ParseXS.
+
+=item * C<$output_expr_ref>
+
+  {
+    'T_CALLBACK' => '	sv_setpvn($arg, $var.context.value().chp(),
+  		$var.context.value().size());
+  ',
+    'T_OUT' => '	{
+  	    GV *gv = newGVgen("$Package");
+  	    if ( do_open(gv, "+>&", 3, FALSE, 0, 0, $var) )
+  		sv_setsv($arg, sv_bless(newRV((SV*)gv), gv_stashpv("$Package",1)));
+  	    else
+  		$arg = &PL_sv_undef;
+  	}
+  ',
+    # ...
+  }
+
+Keys:  Perl API calls B<CONFIRM!>.  Values:  Newline-terminated strings that
+will be written to C source code (F<.c>) files.   The strings are C code, but
+with Perl variables whose values will be interpolated at F<xsubpp>'s runtime
+by one of the C<eval EXPR> statements in ExtUtils::ParseXS.
+
+=back
 
 =back
 
-- 
2.7.4