ParseXS: refactor: update field code comments

Update the code comments in calls to $build_subclass->() to indicate
more consistently the 'type' of each field being declared.

Author: iabyn

dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS/Node.pm

@@ -238,7 +238,7 @@ BEGIN { $build_subclass->(parent => '',
 
     'map_alias_name_to_value', # Hash: maps seen alias names to their value
 
-    'map_alias_value_to_name_seen_hash', # Hash of hash of bools:
+    'map_alias_value_to_name_seen_hash', # Hash of Hash of Bools:
                                # indicates which alias names have been
                                # used for each value.
 
@@ -251,15 +251,15 @@ BEGIN { $build_subclass->(parent => '',
                                # name, map the short (PREFIX removed) name
                                # to the original name.
 
-    'overload_name_seen',      # Hash of bools: indicates overload method
+    'overload_name_seen',      # Hash of Bools: indicates overload method
                                # names (such as '<=>') which have been
                                # listed by OVERLOAD (for newXS boot code
                                # emitting).
 
     # Maintain the ATTRS parsing state across potentially multiple
     # ATTRS keywords and or lines:
 
-    'attributes',              # Array of strings: all ATTRIBUTE keywords
+    'attributes',              # Array of Strs: all ATTRIBUTE keywords
                                # (possibly multiple space-separated
                                # keywords per string).
 
@@ -278,7 +278,7 @@ BEGIN { $build_subclass->(parent => '',
                                #    "2": empty prototype
                                #    other: a specific prototype.
 
-    'SCOPE_enabled',           # "SCOPE: ENABLE" seen, in either the
+    'SCOPE_enabled',           # Bool: "SCOPE: ENABLE" seen, in either the
                                # file or XSUB part of the XS file
 
 )};
@@ -789,10 +789,10 @@ package ExtUtils::ParseXS::Node::ReturnType;
 # extra keywords to process, such as NO_RETURN.
 
 BEGIN { $build_subclass->(parent => '',
-    'type',           # Str: the XSUB's C return type
-    'no_output',      # bool: saw 'NO_OUTPUT'
-    'extern_C',       # bool: saw 'extern C'
-    'static',         # bool: saw 'static'
+    'type',           # Str:  the XSUB's C return type
+    'no_output',      # Bool: saw 'NO_OUTPUT'
+    'extern_C',       # Bool: saw 'extern C'
+    'static',         # Bool: saw 'static'
     'use_early_targ', # Bool: emit an early dTARG for backcompat
 )};
 
@@ -879,23 +879,24 @@ package ExtUtils::ParseXS::Node::Param;
 
 BEGIN { $build_subclass->(parent => '',
     # values derived from the XSUB's signature
-    'in_out',        # The IN/OUT/OUTLIST etc value (if any)
-    'var',           # the name of the parameter
-    'arg_num',       # The arg number (starting at 1) mapped to this param
-    'default',       # default value (if any)
-    'default_usage', # how to report default value in "usage:..." error
-    'is_ansi',       # param's type was specified in signature
-    'is_length',     # param is declared as 'length(foo)' in signature
-    'has_length',    # this param has a matching 'length(foo)' param in sig
-    'len_name' ,     # the 'foo' in 'length(foo)' in signature
-    'is_synthetic',  # var like 'THIS' - we pretend it was in the sig
+    'in_out',        # Str:  The IN/OUT/OUTLIST etc value (if any)
+    'var',           # Str:  the name of the parameter
+    'arg_num',       # Int   The arg number (starting at 1) mapped to this param
+    'default',       # Str:  default value (if any)
+    'default_usage', # Str:  how to report default value in "usage:..." error
+    'is_ansi',       # Bool: param's type was specified in signature
+    'is_length',     # Bool: param is declared as 'length(foo)' in signature
+    'has_length',    # Bool: this param has a matching 'length(foo)'
+                     #       parameter in the signature
+    'len_name' ,     # Str:  the 'foo' in 'length(foo)' in signature
+    'is_synthetic',  # Bool: var like 'THIS': we pretend it was in the sig
 
     # values derived from both the XSUB's signature and/or INPUT line
-    'type',          # The C type of the parameter
-    'no_init',       # don't initialise the parameter
+    'type',          # Str:  The C type of the parameter
+    'no_init',       # Bool: don't initialise the parameter
 
     # derived values calculated later
-    'proto',         # overridden prototype char(s) (if any) from typemap
+    'proto',         # Str: overridden prototype char(s) (if any) from typemap
 )};
 
 
@@ -1101,18 +1102,18 @@ package ExtUtils::ParseXS::Node::IO_Param;
 BEGIN { $build_subclass->(parent => 'Param',
     # values derived from the XSUB's INPUT line
 
-    'init_op',     # initialisation type: one of =/+/;
-    'init',        # initialisation template code
-    'is_addr',     # INPUT var declared as '&foo'
-    'is_alien',    # var declared in INPUT line, but not in signature
-    'in_input',    # the parameter has appeared in an INPUT statement
-    'defer',       # deferred initialisation template code
+    'init_op',     # Str:  initialisation type: one of =/+/;
+    'init',        # Str:  initialisation template code
+    'is_addr',     # Bool: INPUT var declared as '&foo'
+    'is_alien',    # Bool: var declared in INPUT line, but not in signature
+    'in_input',    # Bool: the parameter has appeared in an INPUT statement
+    'defer',       # Str:  deferred initialisation template code
 
     # values derived from the XSUB's OUTPUT line
     #
-    'in_output',   # the parameter has appeared in an OUTPUT statement
-    'do_setmagic', # 'SETMAGIC: ENABLE' was active for this parameter
-    'output_code', # the optional setting-code for this parameter
+    'in_output',   # Bool: the parameter has appeared in an OUTPUT statement
+    'do_setmagic', # Bool: 'SETMAGIC: ENABLE' was active for this parameter
+    'output_code', # Str:  the optional setting-code for this parameter
 
     # ArrayRefs: results of looking up typemaps (which are done in the
     # parse phase, as the typemap definitions can in theory change
@@ -2140,15 +2141,15 @@ BEGIN { $build_subclass->(parent => '',
     'names',         # Hash ref mapping variable names to Node::Param
                      # or Node::IO_Param objects
 
-    'params_text',   # The original text of the sig, e.g.
-                     #   'param1, int param2 = 0'
+    'params_text',   # Str:  The original text of the sig, e.g.
+                     #         "param1, int param2 = 0"
 
     'seen_ellipsis', # Bool: XSUB signature has (   ,...)
 
-    'nargs',         # The number of args expected from caller
-    'min_args',      # The minimum number of args allowed from caller
+    'nargs',         # Int:  The number of args expected from caller
+    'min_args',      # Int:  The minimum number of args allowed from caller
 
-    'auto_function_sig_override', # the C_ARGS value, if any
+    'auto_function_sig_override', # Str: the C_ARGS value, if any
 )};
 
 
@@ -2461,12 +2462,11 @@ package ExtUtils::ParseXS::Node::xbody;
 # higher-level node.
 
 BEGIN { $build_subclass->(parent => '',
-    'ioparams', # per-body copy of params which accumulate extra
-                # info from any INPUT and OUTPUT sections (which can
+    'ioparams', # Params object: per-body copy of params which accumulate
+                # extra info from any INPUT and OUTPUT sections (which can
                 # vary between different CASEs)
 
-
-    # Objects representing the various parts of an xbody. These
+    # Node objects representing the various parts of an xbody. These
     # are aliases of the same objects in @{$self->{kids}} for easier
     # access.
     'input_part',
@@ -2579,11 +2579,10 @@ package ExtUtils::ParseXS::Node::input_part;
 
 BEGIN { $build_subclass->(parent => '',
 
-    # Used during code generation:
+    # Str: used during code generation:
     # a multi-line string containing lines of code to be emitted *after*
     # all INPUT and PREINIT keywords have been processed.
     'deferred_code_lines',
-
 )};
 
 
@@ -3055,7 +3054,7 @@ package ExtUtils::ParseXS::Node::oneline;
 # follows the keyword.
 
 BEGIN { $build_subclass->(parent => '',
-    'text',    # any text following the keyword
+    'text',    # Str: any text following the keyword
 )};
 
 
@@ -3098,8 +3097,8 @@ package ExtUtils::ParseXS::Node::CASE;
 # Process the 'CASE:' keyword
 
 BEGIN { $build_subclass->(parent => 'oneline',
-    'cond',  # the C code of the condition for the CASE, or ''
-    'num',   # which CASE number this is (starting at 1)
+    'cond',  # Str: the C code of the condition for the CASE, or ''
+    'num',   # Int: which CASE number this is (starting at 1)
 )};
 
 
@@ -3136,7 +3135,7 @@ package ExtUtils::ParseXS::Node::autocall;
 # name
 
 BEGIN { $build_subclass->(parent => '',
-    'args', # string to use for auto function call arguments
+    'args', # Str: text to use for auto function call arguments
 )};
 
 
@@ -3232,7 +3231,7 @@ package ExtUtils::ParseXS::Node::enable;
 # Base class for keywords which accept ENABLE/DISABLE as an argument
 
 BEGIN { $build_subclass->(parent => 'oneline',
-    'enable',  # bool
+    'enable',  # Bool
 )};
 
 
@@ -3393,7 +3392,7 @@ package ExtUtils::ParseXS::Node::multiline;
 # follows the keyword.
 
 BEGIN { $build_subclass->(parent => '',
-    'lines',    # Array ref of all lines until the next keyword
+    'lines', # Array ref of all lines until the next keyword
 )};
 
 
@@ -3431,7 +3430,7 @@ package ExtUtils::ParseXS::Node::multiline_merged;
 # into a single line, 'text'.
 
 BEGIN { $build_subclass->(parent => 'multiline',
-    'text',    # singe string contained all concatenated lines
+    'text', # Str: singe string containing all concatenated lines
 )};
 
 
@@ -3532,8 +3531,8 @@ package ExtUtils::ParseXS::Node::INTERFACE_MACRO;
 # Handle INTERFACE_MACRO keyword
 
 BEGIN { $build_subclass->(parent => 'multiline_merged',
-    'get_macro', # name of macro to get interface
-    'set_macro', # name of macro to set interface
+    'get_macro', # Str: name of macro to get interface
+    'set_macro', # Str: name of macro to set interface
 )};
 
 
@@ -3572,7 +3571,7 @@ package ExtUtils::ParseXS::Node::OVERLOAD;
 # Handle OVERLOAD keyword
 
 BEGIN { $build_subclass->(parent => 'multiline_merged',
-    'ops', # has ref of overloaded op names
+    'ops', # Hash ref of seen overloaded op names
 )};
 
 # Add all overload method names, like 'cmp', '<=>', etc, (possibly
@@ -3634,7 +3633,7 @@ package ExtUtils::ParseXS::Node::PROTOTYPE;
 # Handle PROTOTYPE keyword
 
 BEGIN { $build_subclass->(parent => 'multiline',
-    'prototype', # 0 (disable), 1 (enable), 2 ("") or "$$@" etc
+    'prototype', # Str: 0 (disable), 1 (enable), 2 ("") or "$$@" etc
 )};
 
 
@@ -3998,7 +3997,7 @@ package ExtUtils::ParseXS::Node::keyline;
 # their parent.
 
 BEGIN { $build_subclass->(parent => '',
-    'line',   # text of current line
+    'line',   # Str: text of current line
 )};
 
 
@@ -4029,7 +4028,8 @@ package ExtUtils::ParseXS::Node::ALIAS;
 # Handle ALIAS keyword
 
 BEGIN { $build_subclass->(parent => 'keylines',
-    'aliases', # hashref of all alias => value pairs
+    'aliases', # hashref of all alias => value pairs.
+               # Populated by ALIAS_line::parse()
 )};
 
 sub parse {
@@ -4195,8 +4195,8 @@ package ExtUtils::ParseXS::Node::INPUT;
 # block which can follow an xsub signature or CASE keyword.
 
 BEGIN { $build_subclass->(parent => 'keylines',
-    'implicit',   # bool: this is an INPUT section at the start of the
-                  #       XSUB without an explicit 'INPUT' keyword
+    'implicit',   # Bool: this is an INPUT section at the start of the
+                  #       XSUB/CASE, without an explicit 'INPUT' keyword
 )};
 
 # The inherited parse() method will call INPUT_line->parse() for each line
@@ -4228,11 +4228,11 @@ BEGIN { $build_subclass->(parent => 'keyline',
     'param',   # The IO_Param object associated with this INPUT line.
 
                # The parsed components of this INPUT line:
-    'type',    #   char *
-    'is_addr', #           &
-    'name',    #            foo
-    'init_op', #                =
-    'init',    #                   SvIv($arg)
+    'type',    # Str:  char *
+    'is_addr', # Bool:         &
+    'name',    # Str:           foo
+    'init_op', # Str:                =
+    'init',    # Str:                  SvIv($arg)
 )};
 
 
@@ -4481,11 +4481,11 @@ package ExtUtils::ParseXS::Node::OUTPUT_line;
 # Handle one line from an OUTPUT keyword block
 
 BEGIN { $build_subclass->(parent => 'keyline',
-    'param',       # the param object associated with this OUTPUT line.
-    'is_setmagic', # bool: the line is a SETMAGIC: line
-    'do_setmagic', # bool: the current SETMAGIC state
-    'name',        # name of the parameter to output
-    'code',        # optional setting code
+    'param',       # the IO_Param object associated with this OUTPUT line.
+    'is_setmagic', # Bool: the line is a SETMAGIC: line
+    'do_setmagic', # Bool: the current SETMAGIC state
+    'name',        # Str:  name of the parameter to output
+    'code',        # Str:  optional setting code
 )};