Add documentation on the hashrefs produced by process_typemaps().

diff --git a/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS/Utilities.pm b/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS/Utilities.pm
index b25df02..16494d3 100644 (file)
--- 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