prism 0.30.0 → 1.0.0

data/include/prism/ast.h

@@ -1,10 +1,10 @@
-/******************************************************************************/
+/*----------------------------------------------------------------------------*/
 /* This file is generated by the templates/template.rb script and should not  */
 /* be modified manually. See                                                  */
 /* templates/include/prism/ast.h.erb                                          */
 /* if you are looking to modify the                                           */
 /* template                                                                   */
-/******************************************************************************/
+/*----------------------------------------------------------------------------*/
 
 /**
  * @file ast.h
@@ -1043,11 +1043,8 @@ typedef uint16_t pm_node_flags_t;
  * We store the flags enum in every node in the tree. Some flags are common to
  * all nodes (the ones listed below). Others are specific to certain node types.
  */
-#define PM_NODE_FLAG_BITS (sizeof(pm_node_flags_t) * 8)
-
-static const pm_node_flags_t PM_NODE_FLAG_NEWLINE = (1 << (PM_NODE_FLAG_BITS - 1));
-static const pm_node_flags_t PM_NODE_FLAG_STATIC_LITERAL = (1 << (PM_NODE_FLAG_BITS - 2));
-static const pm_node_flags_t PM_NODE_FLAG_COMMON_MASK = (1 << (PM_NODE_FLAG_BITS - 1)) | (1 << (PM_NODE_FLAG_BITS - 2));
+static const pm_node_flags_t PM_NODE_FLAG_NEWLINE = 0x1;
+static const pm_node_flags_t PM_NODE_FLAG_STATIC_LITERAL = 0x2;
 
 /**
  * Cast the type to an enum to allow the compiler to provide exhaustiveness
@@ -1082,6 +1079,12 @@ typedef struct pm_node {
      */
     pm_node_flags_t flags;
 
+    /**
+     * The unique identifier for this node, which is deterministic based on the
+     * source. It is used to identify unique nodes across parses.
+     */
+    uint32_t node_id;
+
     /**
      * This is the location of the node in the source. It's a range of bytes
      * containing a start and an end.
@@ -1092,6 +1095,11 @@ typedef struct pm_node {
 /**
  * AliasGlobalVariableNode
  *
+ * Represents the use of the `alias` keyword to alias a global variable.
+ *
+ *     alias $foo $bar
+ *     ^^^^^^^^^^^^^^^
+ *
  * Type: PM_ALIAS_GLOBAL_VARIABLE_NODE
  *
  * @extends pm_node_t
@@ -1103,7 +1111,7 @@ typedef struct pm_alias_global_variable_node {
     /**
      * AliasGlobalVariableNode#new_name
      *
-     * Represents the new name of the global variable that can be used after aliasing. This can be either a global variable, a back reference, or a numbered reference.
+     * Represents the new name of the global variable that can be used after aliasing.
      *
      *     alias $foo $bar
      *           ^^^^
@@ -1113,7 +1121,7 @@ typedef struct pm_alias_global_variable_node {
     /**
      * AliasGlobalVariableNode#old_name
      *
-     * Represents the old name of the global variable that could be used before aliasing. This can be either a global variable, a back reference, or a numbered reference.
+     * Represents the old name of the global variable that can be used before aliasing.
      *
      *     alias $foo $bar
      *                ^^^^
@@ -1134,6 +1142,11 @@ typedef struct pm_alias_global_variable_node {
 /**
  * AliasMethodNode
  *
+ * Represents the use of the `alias` keyword to alias a method.
+ *
+ *     alias foo bar
+ *     ^^^^^^^^^^^^^
+ *
  * Type: PM_ALIAS_METHOD_NODE
  *
  * @extends pm_node_t
@@ -1161,6 +1174,11 @@ typedef struct pm_alias_method_node {
 /**
  * AlternationPatternNode
  *
+ * Represents an alternation pattern in pattern matching.
+ *
+ *     foo => bar | baz
+ *            ^^^^^^^^^
+ *
  * Type: PM_ALTERNATION_PATTERN_NODE
  *
  * @extends pm_node_t
@@ -1188,6 +1206,11 @@ typedef struct pm_alternation_pattern_node {
 /**
  * AndNode
  *
+ * Represents the use of the `&&` operator or the `and` keyword.
+ *
+ *     left and right
+ *     ^^^^^^^^^^^^^^
+ *
  * Type: PM_AND_NODE
  *
  * @extends pm_node_t
@@ -1236,10 +1259,16 @@ typedef struct pm_and_node {
 /**
  * ArgumentsNode
  *
+ * Represents a set of arguments to a method or a keyword.
+ *
+ *     return foo, bar, baz
+ *            ^^^^^^^^^^^^^
+ *
  * Type: PM_ARGUMENTS_NODE
  * Flags:
  *    PM_ARGUMENTS_NODE_FLAGS_CONTAINS_KEYWORDS
  *    PM_ARGUMENTS_NODE_FLAGS_CONTAINS_KEYWORD_SPLAT
+ *    PM_ARGUMENTS_NODE_FLAGS_CONTAINS_SPLAT
  *
  * @extends pm_node_t
  */
@@ -1256,6 +1285,11 @@ typedef struct pm_arguments_node {
 /**
  * ArrayNode
  *
+ * Represents an array literal. This can be a regular array using brackets or a special array using % like %w or %i.
+ *
+ *     [1, 2, 3]
+ *     ^^^^^^^^^
+ *
  * Type: PM_ARRAY_NODE
  * Flags:
  *    PM_ARRAY_NODE_FLAGS_CONTAINS_SPLAT
@@ -1301,6 +1335,23 @@ typedef struct pm_array_node {
 /**
  * ArrayPatternNode
  *
+ * Represents an array pattern in pattern matching.
+ *
+ *     foo in 1, 2
+ *     ^^^^^^^^^^^
+ *
+ *     foo in [1, 2]
+ *     ^^^^^^^^^^^^^
+ *
+ *     foo in *1
+ *     ^^^^^^^^^
+ *
+ *     foo in Bar[]
+ *     ^^^^^^^^^^^^
+ *
+ *     foo in Bar[1, 2, 3]
+ *     ^^^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_ARRAY_PATTERN_NODE
  *
  * @extends pm_node_t
@@ -1343,6 +1394,11 @@ typedef struct pm_array_pattern_node {
 /**
  * AssocNode
  *
+ * Represents a hash key/value pair.
+ *
+ *     { a => b }
+ *       ^^^^^^
+ *
  * Type: PM_ASSOC_NODE
  *
  * @extends pm_node_t
@@ -1394,6 +1450,11 @@ typedef struct pm_assoc_node {
 /**
  * AssocSplatNode
  *
+ * Represents a splat in a hash literal.
+ *
+ *     { **foo }
+ *       ^^^^^
+ *
  * Type: PM_ASSOC_SPLAT_NODE
  *
  * @extends pm_node_t
@@ -1426,6 +1487,11 @@ typedef struct pm_assoc_splat_node {
 /**
  * BackReferenceReadNode
  *
+ * Represents reading a reference to a field in the previous match.
+ *
+ *     $'
+ *     ^^
+ *
  * Type: PM_BACK_REFERENCE_READ_NODE
  *
  * @extends pm_node_t
@@ -1449,6 +1515,13 @@ typedef struct pm_back_reference_read_node {
 /**
  * BeginNode
  *
+ * Represents a begin statement.
+ *
+ *     begin
+ *       foo
+ *     end
+ *     ^^^^^
+ *
  * Type: PM_BEGIN_NODE
  *
  * @extends pm_node_t
@@ -1491,6 +1564,11 @@ typedef struct pm_begin_node {
 /**
  * BlockArgumentNode
  *
+ * Represents a block argument using `&`.
+ *
+ *     bar(&args)
+ *     ^^^^^^^^^^
+ *
  * Type: PM_BLOCK_ARGUMENT_NODE
  *
  * @extends pm_node_t
@@ -1513,6 +1591,11 @@ typedef struct pm_block_argument_node {
 /**
  * BlockLocalVariableNode
  *
+ * Represents a block local variable.
+ *
+ *     a { |; b| }
+ *            ^
+ *
  * Type: PM_BLOCK_LOCAL_VARIABLE_NODE
  * Flags:
  *    PM_PARAMETER_FLAGS_REPEATED_PARAMETER
@@ -1532,6 +1615,11 @@ typedef struct pm_block_local_variable_node {
 /**
  * BlockNode
  *
+ * Represents a block of ruby code.
+ *
+ *     [1, 2, 3].each { |i| puts x }
+ *                    ^^^^^^^^^^^^^^
+ *
  * Type: PM_BLOCK_NODE
  *
  * @extends pm_node_t
@@ -1569,6 +1657,12 @@ typedef struct pm_block_node {
 /**
  * BlockParameterNode
  *
+ * Represents a block parameter of a method, block, or lambda definition.
+ *
+ *     def a(&b)
+ *           ^^
+ *     end
+ *
  * Type: PM_BLOCK_PARAMETER_NODE
  * Flags:
  *    PM_PARAMETER_FLAGS_REPEATED_PARAMETER
@@ -1598,6 +1692,15 @@ typedef struct pm_block_parameter_node {
 /**
  * BlockParametersNode
  *
+ * Represents a block's parameters declaration.
+ *
+ *     -> (a, b = 1; local) { }
+ *        ^^^^^^^^^^^^^^^^^
+ *
+ *     foo do |a, b = 1; local|
+ *            ^^^^^^^^^^^^^^^^^
+ *     end
+ *
  * Type: PM_BLOCK_PARAMETERS_NODE
  *
  * @extends pm_node_t
@@ -1630,6 +1733,11 @@ typedef struct pm_block_parameters_node {
 /**
  * BreakNode
  *
+ * Represents the use of the `break` keyword.
+ *
+ *     break foo
+ *     ^^^^^^^^^
+ *
  * Type: PM_BREAK_NODE
  *
  * @extends pm_node_t
@@ -1662,6 +1770,11 @@ typedef struct pm_break_node {
 /**
  * CallAndWriteNode
  *
+ * Represents the use of the `&&=` operator on a call.
+ *
+ *     foo.bar &&= value
+ *     ^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_CALL_AND_WRITE_NODE
  * Flags:
  *    PM_CALL_NODE_FLAGS_SAFE_NAVIGATION
@@ -1714,6 +1827,26 @@ typedef struct pm_call_and_write_node {
 /**
  * CallNode
  *
+ * Represents a method call, in all of the various forms that can take.
+ *
+ *     foo
+ *     ^^^
+ *
+ *     foo()
+ *     ^^^^^
+ *
+ *     +foo
+ *     ^^^^
+ *
+ *     foo + bar
+ *     ^^^^^^^^^
+ *
+ *     foo.bar
+ *     ^^^^^^^
+ *
+ *     foo&.bar
+ *     ^^^^^^^^
+ *
  * Type: PM_CALL_NODE
  * Flags:
  *    PM_CALL_NODE_FLAGS_SAFE_NAVIGATION
@@ -1782,6 +1915,11 @@ typedef struct pm_call_node {
 /**
  * CallOperatorWriteNode
  *
+ * Represents the use of an assignment operator on a call.
+ *
+ *     foo.bar += baz
+ *     ^^^^^^^^^^^^^^
+ *
  * Type: PM_CALL_OPERATOR_WRITE_NODE
  * Flags:
  *    PM_CALL_NODE_FLAGS_SAFE_NAVIGATION
@@ -1839,6 +1977,11 @@ typedef struct pm_call_operator_write_node {
 /**
  * CallOrWriteNode
  *
+ * Represents the use of the `||=` operator on a call.
+ *
+ *     foo.bar ||= value
+ *     ^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_CALL_OR_WRITE_NODE
  * Flags:
  *    PM_CALL_NODE_FLAGS_SAFE_NAVIGATION
@@ -1891,6 +2034,19 @@ typedef struct pm_call_or_write_node {
 /**
  * CallTargetNode
  *
+ * Represents assigning to a method call.
+ *
+ *     foo.bar, = 1
+ *     ^^^^^^^
+ *
+ *     begin
+ *     rescue => foo.bar
+ *               ^^^^^^^
+ *     end
+ *
+ *     for foo.bar in baz do end
+ *         ^^^^^^^
+ *
  * Type: PM_CALL_TARGET_NODE
  * Flags:
  *    PM_CALL_NODE_FLAGS_SAFE_NAVIGATION
@@ -1928,6 +2084,11 @@ typedef struct pm_call_target_node {
 /**
  * CapturePatternNode
  *
+ * Represents assigning to a local variable in pattern matching.
+ *
+ *     foo => [bar => baz]
+ *            ^^^^^^^^^^^^
+ *
  * Type: PM_CAPTURE_PATTERN_NODE
  *
  * @extends pm_node_t
@@ -1955,6 +2116,13 @@ typedef struct pm_capture_pattern_node {
 /**
  * CaseMatchNode
  *
+ * Represents the use of a case statement for pattern matching.
+ *
+ *     case true
+ *     in false
+ *     end
+ *     ^^^^^^^^^
+ *
  * Type: PM_CASE_MATCH_NODE
  *
  * @extends pm_node_t
@@ -1974,9 +2142,9 @@ typedef struct pm_case_match_node {
     struct pm_node_list conditions;
 
     /**
-     * CaseMatchNode#consequent
+     * CaseMatchNode#else_clause
      */
-    struct pm_else_node *consequent;
+    struct pm_else_node *else_clause;
 
     /**
      * CaseMatchNode#case_keyword_loc
@@ -1992,6 +2160,13 @@ typedef struct pm_case_match_node {
 /**
  * CaseNode
  *
+ * Represents the use of a case statement.
+ *
+ *     case true
+ *     when false
+ *     end
+ *     ^^^^^^^^^^
+ *
  * Type: PM_CASE_NODE
  *
  * @extends pm_node_t
@@ -2011,9 +2186,9 @@ typedef struct pm_case_node {
     struct pm_node_list conditions;
 
     /**
-     * CaseNode#consequent
+     * CaseNode#else_clause
      */
-    struct pm_else_node *consequent;
+    struct pm_else_node *else_clause;
 
     /**
      * CaseNode#case_keyword_loc
@@ -2029,6 +2204,11 @@ typedef struct pm_case_node {
 /**
  * ClassNode
  *
+ * Represents a class declaration involving the `class` keyword.
+ *
+ *     class Foo end
+ *     ^^^^^^^^^^^^^
+ *
  * Type: PM_CLASS_NODE
  *
  * @extends pm_node_t
@@ -2081,6 +2261,11 @@ typedef struct pm_class_node {
 /**
  * ClassVariableAndWriteNode
  *
+ * Represents the use of the `&&=` operator for assignment to a class variable.
+ *
+ *     @@target &&= value
+ *     ^^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_CLASS_VARIABLE_AND_WRITE_NODE
  *
  * @extends pm_node_t
@@ -2113,6 +2298,11 @@ typedef struct pm_class_variable_and_write_node {
 /**
  * ClassVariableOperatorWriteNode
  *
+ * Represents assigning to a class variable using an operator that isn't `=`.
+ *
+ *     @@target += value
+ *     ^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_CLASS_VARIABLE_OPERATOR_WRITE_NODE
  *
  * @extends pm_node_t
@@ -2150,6 +2340,11 @@ typedef struct pm_class_variable_operator_write_node {
 /**
  * ClassVariableOrWriteNode
  *
+ * Represents the use of the `||=` operator for assignment to a class variable.
+ *
+ *     @@target ||= value
+ *     ^^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_CLASS_VARIABLE_OR_WRITE_NODE
  *
  * @extends pm_node_t
@@ -2182,6 +2377,11 @@ typedef struct pm_class_variable_or_write_node {
 /**
  * ClassVariableReadNode
  *
+ * Represents referencing a class variable.
+ *
+ *     @@foo
+ *     ^^^^^
+ *
  * Type: PM_CLASS_VARIABLE_READ_NODE
  *
  * @extends pm_node_t
@@ -2205,6 +2405,11 @@ typedef struct pm_class_variable_read_node {
 /**
  * ClassVariableTargetNode
  *
+ * Represents writing to a class variable in a context that doesn't have an explicit value.
+ *
+ *     @@foo, @@bar = baz
+ *     ^^^^^  ^^^^^
+ *
  * Type: PM_CLASS_VARIABLE_TARGET_NODE
  *
  * @extends pm_node_t
@@ -2222,6 +2427,11 @@ typedef struct pm_class_variable_target_node {
 /**
  * ClassVariableWriteNode
  *
+ * Represents writing to a class variable.
+ *
+ *     @@foo = 1
+ *     ^^^^^^^^^
+ *
  * Type: PM_CLASS_VARIABLE_WRITE_NODE
  *
  * @extends pm_node_t
@@ -2278,6 +2488,11 @@ typedef struct pm_class_variable_write_node {
 /**
  * ConstantAndWriteNode
  *
+ * Represents the use of the `&&=` operator for assignment to a constant.
+ *
+ *     Target &&= value
+ *     ^^^^^^^^^^^^^^^^
+ *
  * Type: PM_CONSTANT_AND_WRITE_NODE
  *
  * @extends pm_node_t
@@ -2310,6 +2525,11 @@ typedef struct pm_constant_and_write_node {
 /**
  * ConstantOperatorWriteNode
  *
+ * Represents assigning to a constant using an operator that isn't `=`.
+ *
+ *     Target += value
+ *     ^^^^^^^^^^^^^^^
+ *
  * Type: PM_CONSTANT_OPERATOR_WRITE_NODE
  *
  * @extends pm_node_t
@@ -2347,6 +2567,11 @@ typedef struct pm_constant_operator_write_node {
 /**
  * ConstantOrWriteNode
  *
+ * Represents the use of the `||=` operator for assignment to a constant.
+ *
+ *     Target ||= value
+ *     ^^^^^^^^^^^^^^^^
+ *
  * Type: PM_CONSTANT_OR_WRITE_NODE
  *
  * @extends pm_node_t
@@ -2379,6 +2604,11 @@ typedef struct pm_constant_or_write_node {
 /**
  * ConstantPathAndWriteNode
  *
+ * Represents the use of the `&&=` operator for assignment to a constant path.
+ *
+ *     Parent::Child &&= value
+ *     ^^^^^^^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_CONSTANT_PATH_AND_WRITE_NODE
  *
  * @extends pm_node_t
@@ -2406,6 +2636,11 @@ typedef struct pm_constant_path_and_write_node {
 /**
  * ConstantPathNode
  *
+ * Represents accessing a constant through a path of `::` operators.
+ *
+ *     Foo::Bar
+ *     ^^^^^^^^
+ *
  * Type: PM_CONSTANT_PATH_NODE
  *
  * @extends pm_node_t
@@ -2467,6 +2702,11 @@ typedef struct pm_constant_path_node {
 /**
  * ConstantPathOperatorWriteNode
  *
+ * Represents assigning to a constant path using an operator that isn't `=`.
+ *
+ *     Parent::Child += value
+ *     ^^^^^^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_CONSTANT_PATH_OPERATOR_WRITE_NODE
  *
  * @extends pm_node_t
@@ -2499,6 +2739,11 @@ typedef struct pm_constant_path_operator_write_node {
 /**
  * ConstantPathOrWriteNode
  *
+ * Represents the use of the `||=` operator for assignment to a constant path.
+ *
+ *     Parent::Child ||= value
+ *     ^^^^^^^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_CONSTANT_PATH_OR_WRITE_NODE
  *
  * @extends pm_node_t
@@ -2526,6 +2771,11 @@ typedef struct pm_constant_path_or_write_node {
 /**
  * ConstantPathTargetNode
  *
+ * Represents writing to a constant path in a context that doesn't have an explicit value.
+ *
+ *     Foo::Foo, Bar::Bar = baz
+ *     ^^^^^^^^  ^^^^^^^^
+ *
  * Type: PM_CONSTANT_PATH_TARGET_NODE
  *
  * @extends pm_node_t
@@ -2558,6 +2808,17 @@ typedef struct pm_constant_path_target_node {
 /**
  * ConstantPathWriteNode
  *
+ * Represents writing to a constant path.
+ *
+ *     ::Foo = 1
+ *     ^^^^^^^^^
+ *
+ *     Foo::Bar = 1
+ *     ^^^^^^^^^^^^
+ *
+ *     ::Foo::Bar = 1
+ *     ^^^^^^^^^^^^^^
+ *
  * Type: PM_CONSTANT_PATH_WRITE_NODE
  *
  * @extends pm_node_t
@@ -2603,6 +2864,11 @@ typedef struct pm_constant_path_write_node {
 /**
  * ConstantReadNode
  *
+ * Represents referencing a constant.
+ *
+ *     Foo
+ *     ^^^
+ *
  * Type: PM_CONSTANT_READ_NODE
  *
  * @extends pm_node_t
@@ -2626,6 +2892,11 @@ typedef struct pm_constant_read_node {
 /**
  * ConstantTargetNode
  *
+ * Represents writing to a constant in a context that doesn't have an explicit value.
+ *
+ *     Foo, Bar = baz
+ *     ^^^  ^^^
+ *
  * Type: PM_CONSTANT_TARGET_NODE
  *
  * @extends pm_node_t
@@ -2643,6 +2914,11 @@ typedef struct pm_constant_target_node {
 /**
  * ConstantWriteNode
  *
+ * Represents writing to a constant.
+ *
+ *     Foo = 1
+ *     ^^^^^^^
+ *
  * Type: PM_CONSTANT_WRITE_NODE
  *
  * @extends pm_node_t
@@ -2699,6 +2975,12 @@ typedef struct pm_constant_write_node {
 /**
  * DefNode
  *
+ * Represents a method definition.
+ *
+ *     def method
+ *     end
+ *     ^^^^^^^^^^
+ *
  * Type: PM_DEF_NODE
  *
  * @extends pm_node_t
@@ -2771,6 +3053,11 @@ typedef struct pm_def_node {
 /**
  * DefinedNode
  *
+ * Represents the use of the `defined?` keyword.
+ *
+ *     defined?(a)
+ *     ^^^^^^^^^^^
+ *
  * Type: PM_DEFINED_NODE
  *
  * @extends pm_node_t
@@ -2803,6 +3090,11 @@ typedef struct pm_defined_node {
 /**
  * ElseNode
  *
+ * Represents an `else` clause in a `case`, `if`, or `unless` statement.
+ *
+ *     if a then b else c end
+ *                 ^^^^^^^^^^
+ *
  * Type: PM_ELSE_NODE
  *
  * @extends pm_node_t
@@ -2830,6 +3122,11 @@ typedef struct pm_else_node {
 /**
  * EmbeddedStatementsNode
  *
+ * Represents an interpolated set of statements.
+ *
+ *     "foo #{bar}"
+ *          ^^^^^^
+ *
  * Type: PM_EMBEDDED_STATEMENTS_NODE
  *
  * @extends pm_node_t
@@ -2857,6 +3154,11 @@ typedef struct pm_embedded_statements_node {
 /**
  * EmbeddedVariableNode
  *
+ * Represents an interpolated variable.
+ *
+ *     "foo #@bar"
+ *          ^^^^^
+ *
  * Type: PM_EMBEDDED_VARIABLE_NODE
  *
  * @extends pm_node_t
@@ -2879,6 +3181,15 @@ typedef struct pm_embedded_variable_node {
 /**
  * EnsureNode
  *
+ * Represents an `ensure` clause in a `begin` statement.
+ *
+ *     begin
+ *       foo
+ *     ensure
+ *     ^^^^^^
+ *       bar
+ *     end
+ *
  * Type: PM_ENSURE_NODE
  *
  * @extends pm_node_t
@@ -2906,6 +3217,11 @@ typedef struct pm_ensure_node {
 /**
  * FalseNode
  *
+ * Represents the use of the literal `false` keyword.
+ *
+ *     false
+ *     ^^^^^
+ *
  * Type: PM_FALSE_NODE
  *
  * @extends pm_node_t
@@ -2918,6 +3234,17 @@ typedef struct pm_false_node {
 /**
  * FindPatternNode
  *
+ * Represents a find pattern in pattern matching.
+ *
+ *     foo in *bar, baz, *qux
+ *            ^^^^^^^^^^^^^^^
+ *
+ *     foo in [*bar, baz, *qux]
+ *            ^^^^^^^^^^^^^^^^^
+ *
+ *     foo in Foo(*bar, baz, *qux)
+ *            ^^^^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_FIND_PATTERN_NODE
  *
  * @extends pm_node_t
@@ -2960,6 +3287,11 @@ typedef struct pm_find_pattern_node {
 /**
  * FlipFlopNode
  *
+ * Represents the use of the `..` or `...` operators to create flip flops.
+ *
+ *     baz if foo .. bar
+ *            ^^^^^^^^^^
+ *
  * Type: PM_FLIP_FLOP_NODE
  * Flags:
  *    PM_RANGE_FLAGS_EXCLUDE_END
@@ -2989,6 +3321,11 @@ typedef struct pm_flip_flop_node {
 /**
  * FloatNode
  *
+ * Represents a floating point number literal.
+ *
+ *     1.0
+ *     ^^^
+ *
  * Type: PM_FLOAT_NODE
  *
  * @extends pm_node_t
@@ -3008,6 +3345,11 @@ typedef struct pm_float_node {
 /**
  * ForNode
  *
+ * Represents the use of the `for` keyword.
+ *
+ *     for i in a end
+ *     ^^^^^^^^^^^^^^
+ *
  * Type: PM_FOR_NODE
  *
  * @extends pm_node_t
@@ -3092,6 +3434,13 @@ typedef struct pm_for_node {
 /**
  * ForwardingArgumentsNode
  *
+ * Represents forwarding all arguments to this method to another method.
+ *
+ *     def foo(...)
+ *       bar(...)
+ *           ^^^
+ *     end
+ *
  * Type: PM_FORWARDING_ARGUMENTS_NODE
  *
  * @extends pm_node_t
@@ -3104,6 +3453,12 @@ typedef struct pm_forwarding_arguments_node {
 /**
  * ForwardingParameterNode
  *
+ * Represents the use of the forwarding parameter in a method, block, or lambda declaration.
+ *
+ *     def foo(...)
+ *             ^^^
+ *     end
+ *
  * Type: PM_FORWARDING_PARAMETER_NODE
  *
  * @extends pm_node_t
@@ -3116,6 +3471,11 @@ typedef struct pm_forwarding_parameter_node {
 /**
  * ForwardingSuperNode
  *
+ * Represents the use of the `super` keyword without parentheses or arguments.
+ *
+ *     super
+ *     ^^^^^
+ *
  * Type: PM_FORWARDING_SUPER_NODE
  *
  * @extends pm_node_t
@@ -3133,6 +3493,11 @@ typedef struct pm_forwarding_super_node {
 /**
  * GlobalVariableAndWriteNode
  *
+ * Represents the use of the `&&=` operator for assignment to a global variable.
+ *
+ *     $target &&= value
+ *     ^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_GLOBAL_VARIABLE_AND_WRITE_NODE
  *
  * @extends pm_node_t
@@ -3165,6 +3530,11 @@ typedef struct pm_global_variable_and_write_node {
 /**
  * GlobalVariableOperatorWriteNode
  *
+ * Represents assigning to a global variable using an operator that isn't `=`.
+ *
+ *     $target += value
+ *     ^^^^^^^^^^^^^^^^
+ *
  * Type: PM_GLOBAL_VARIABLE_OPERATOR_WRITE_NODE
  *
  * @extends pm_node_t
@@ -3202,6 +3572,11 @@ typedef struct pm_global_variable_operator_write_node {
 /**
  * GlobalVariableOrWriteNode
  *
+ * Represents the use of the `||=` operator for assignment to a global variable.
+ *
+ *     $target ||= value
+ *     ^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_GLOBAL_VARIABLE_OR_WRITE_NODE
  *
  * @extends pm_node_t
@@ -3234,6 +3609,11 @@ typedef struct pm_global_variable_or_write_node {
 /**
  * GlobalVariableReadNode
  *
+ * Represents referencing a global variable.
+ *
+ *     $foo
+ *     ^^^^
+ *
  * Type: PM_GLOBAL_VARIABLE_READ_NODE
  *
  * @extends pm_node_t
@@ -3257,6 +3637,11 @@ typedef struct pm_global_variable_read_node {
 /**
  * GlobalVariableTargetNode
  *
+ * Represents writing to a global variable in a context that doesn't have an explicit value.
+ *
+ *     $foo, $bar = baz
+ *     ^^^^  ^^^^
+ *
  * Type: PM_GLOBAL_VARIABLE_TARGET_NODE
  *
  * @extends pm_node_t
@@ -3274,6 +3659,11 @@ typedef struct pm_global_variable_target_node {
 /**
  * GlobalVariableWriteNode
  *
+ * Represents writing to a global variable.
+ *
+ *     $foo = 1
+ *     ^^^^^^^^
+ *
  * Type: PM_GLOBAL_VARIABLE_WRITE_NODE
  *
  * @extends pm_node_t
@@ -3330,6 +3720,11 @@ typedef struct pm_global_variable_write_node {
 /**
  * HashNode
  *
+ * Represents a hash literal.
+ *
+ *     { a => b }
+ *     ^^^^^^^^^^
+ *
  * Type: PM_HASH_NODE
  *
  * @extends pm_node_t
@@ -3375,6 +3770,14 @@ typedef struct pm_hash_node {
 /**
  * HashPatternNode
  *
+ * Represents a hash pattern in pattern matching.
+ *
+ *     foo => { a: 1, b: 2 }
+ *            ^^^^^^^^^^^^^^
+ *
+ *     foo => { a: 1, b: 2, **c }
+ *            ^^^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_HASH_PATTERN_NODE
  *
  * @extends pm_node_t
@@ -3412,6 +3815,17 @@ typedef struct pm_hash_pattern_node {
 /**
  * IfNode
  *
+ * Represents the use of the `if` keyword, either in the block form or the modifier form, or a ternary expression.
+ *
+ *     bar if foo
+ *     ^^^^^^^^^^
+ *
+ *     if foo then bar end
+ *     ^^^^^^^^^^^^^^^^^^^
+ *
+ *     foo ? bar : baz
+ *     ^^^^^^^^^^^^^^^
+ *
  * Type: PM_IF_NODE
  *
  * @extends pm_node_t
@@ -3478,7 +3892,7 @@ typedef struct pm_if_node {
     struct pm_statements_node *statements;
 
     /**
-     * IfNode#consequent
+     * IfNode#subsequent
      *
      * Represents an `ElseNode` or an `IfNode` when there is an `else` or an `elsif` in the `if` statement.
      *
@@ -3494,7 +3908,7 @@ typedef struct pm_if_node {
      *     if foo then bar else baz end
      *                     ^^^^^^^^^^^^
      */
-    struct pm_node *consequent;
+    struct pm_node *subsequent;
 
     /**
      * IfNode#end_keyword_loc
@@ -3512,6 +3926,11 @@ typedef struct pm_if_node {
 /**
  * ImaginaryNode
  *
+ * Represents an imaginary number literal.
+ *
+ *     1.0i
+ *     ^^^^
+ *
  * Type: PM_IMAGINARY_NODE
  *
  * @extends pm_node_t
@@ -3529,6 +3948,17 @@ typedef struct pm_imaginary_node {
 /**
  * ImplicitNode
  *
+ * Represents a node that is implicitly being added to the tree but doesn't correspond directly to a node in the source.
+ *
+ *     { foo: }
+ *       ^^^^
+ *
+ *     { Foo: }
+ *       ^^^^
+ *
+ *     foo in { bar: }
+ *              ^^^^
+ *
  * Type: PM_IMPLICIT_NODE
  *
  * @extends pm_node_t
@@ -3546,6 +3976,20 @@ typedef struct pm_implicit_node {
 /**
  * ImplicitRestNode
  *
+ * Represents using a trailing comma to indicate an implicit rest parameter.
+ *
+ *     foo { |bar,| }
+ *               ^
+ *
+ *     foo in [bar,]
+ *                ^
+ *
+ *     for foo, in bar do end
+ *            ^
+ *
+ *     foo, = bar
+ *        ^
+ *
  * Type: PM_IMPLICIT_REST_NODE
  *
  * @extends pm_node_t
@@ -3558,6 +4002,11 @@ typedef struct pm_implicit_rest_node {
 /**
  * InNode
  *
+ * Represents the use of the `in` keyword in a case statement.
+ *
+ *     case a; in b then c end
+ *             ^^^^^^^^^^^
+ *
  * Type: PM_IN_NODE
  *
  * @extends pm_node_t
@@ -3590,6 +4039,11 @@ typedef struct pm_in_node {
 /**
  * IndexAndWriteNode
  *
+ * Represents the use of the `&&=` operator on a call to the `[]` method.
+ *
+ *     foo.bar[baz] &&= value
+ *     ^^^^^^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_INDEX_AND_WRITE_NODE
  * Flags:
  *    PM_CALL_NODE_FLAGS_SAFE_NAVIGATION
@@ -3647,6 +4101,11 @@ typedef struct pm_index_and_write_node {
 /**
  * IndexOperatorWriteNode
  *
+ * Represents the use of an assignment operator on a call to `[]`.
+ *
+ *     foo.bar[baz] += value
+ *     ^^^^^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_INDEX_OPERATOR_WRITE_NODE
  * Flags:
  *    PM_CALL_NODE_FLAGS_SAFE_NAVIGATION
@@ -3709,6 +4168,11 @@ typedef struct pm_index_operator_write_node {
 /**
  * IndexOrWriteNode
  *
+ * Represents the use of the `||=` operator on a call to `[]`.
+ *
+ *     foo.bar[baz] ||= value
+ *     ^^^^^^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_INDEX_OR_WRITE_NODE
  * Flags:
  *    PM_CALL_NODE_FLAGS_SAFE_NAVIGATION
@@ -3766,6 +4230,19 @@ typedef struct pm_index_or_write_node {
 /**
  * IndexTargetNode
  *
+ * Represents assigning to an index.
+ *
+ *     foo[bar], = 1
+ *     ^^^^^^^^
+ *
+ *     begin
+ *     rescue => foo[bar]
+ *               ^^^^^^^^
+ *     end
+ *
+ *     for foo[bar] in baz do end
+ *         ^^^^^^^^
+ *
  * Type: PM_INDEX_TARGET_NODE
  * Flags:
  *    PM_CALL_NODE_FLAGS_SAFE_NAVIGATION
@@ -3808,6 +4285,11 @@ typedef struct pm_index_target_node {
 /**
  * InstanceVariableAndWriteNode
  *
+ * Represents the use of the `&&=` operator for assignment to an instance variable.
+ *
+ *     @target &&= value
+ *     ^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_INSTANCE_VARIABLE_AND_WRITE_NODE
  *
  * @extends pm_node_t
@@ -3840,6 +4322,11 @@ typedef struct pm_instance_variable_and_write_node {
 /**
  * InstanceVariableOperatorWriteNode
  *
+ * Represents assigning to an instance variable using an operator that isn't `=`.
+ *
+ *     @target += value
+ *     ^^^^^^^^^^^^^^^^
+ *
  * Type: PM_INSTANCE_VARIABLE_OPERATOR_WRITE_NODE
  *
  * @extends pm_node_t
@@ -3877,6 +4364,11 @@ typedef struct pm_instance_variable_operator_write_node {
 /**
  * InstanceVariableOrWriteNode
  *
+ * Represents the use of the `||=` operator for assignment to an instance variable.
+ *
+ *     @target ||= value
+ *     ^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_INSTANCE_VARIABLE_OR_WRITE_NODE
  *
  * @extends pm_node_t
@@ -3909,6 +4401,11 @@ typedef struct pm_instance_variable_or_write_node {
 /**
  * InstanceVariableReadNode
  *
+ * Represents referencing an instance variable.
+ *
+ *     @foo
+ *     ^^^^
+ *
  * Type: PM_INSTANCE_VARIABLE_READ_NODE
  *
  * @extends pm_node_t
@@ -3932,6 +4429,11 @@ typedef struct pm_instance_variable_read_node {
 /**
  * InstanceVariableTargetNode
  *
+ * Represents writing to an instance variable in a context that doesn't have an explicit value.
+ *
+ *     @foo, @bar = baz
+ *     ^^^^  ^^^^
+ *
  * Type: PM_INSTANCE_VARIABLE_TARGET_NODE
  *
  * @extends pm_node_t
@@ -3949,6 +4451,11 @@ typedef struct pm_instance_variable_target_node {
 /**
  * InstanceVariableWriteNode
  *
+ * Represents writing to an instance variable.
+ *
+ *     @foo = 1
+ *     ^^^^^^^^
+ *
  * Type: PM_INSTANCE_VARIABLE_WRITE_NODE
  *
  * @extends pm_node_t
@@ -4005,6 +4512,11 @@ typedef struct pm_instance_variable_write_node {
 /**
  * IntegerNode
  *
+ * Represents an integer number literal.
+ *
+ *     1
+ *     ^
+ *
  * Type: PM_INTEGER_NODE
  * Flags:
  *    PM_INTEGER_BASE_FLAGS_BINARY
@@ -4029,6 +4541,11 @@ typedef struct pm_integer_node {
 /**
  * InterpolatedMatchLastLineNode
  *
+ * Represents a regular expression literal that contains interpolation that is being used in the predicate of a conditional to implicitly match against the last line read by an IO object.
+ *
+ *     if /foo #{bar} baz/ then end
+ *        ^^^^^^^^^^^^^^^^
+ *
  * Type: PM_INTERPOLATED_MATCH_LAST_LINE_NODE
  * Flags:
  *    PM_REGULAR_EXPRESSION_FLAGS_IGNORE_CASE
@@ -4068,6 +4585,11 @@ typedef struct pm_interpolated_match_last_line_node {
 /**
  * InterpolatedRegularExpressionNode
  *
+ * Represents a regular expression literal that contains interpolation.
+ *
+ *     /foo #{bar} baz/
+ *     ^^^^^^^^^^^^^^^^
+ *
  * Type: PM_INTERPOLATED_REGULAR_EXPRESSION_NODE
  * Flags:
  *    PM_REGULAR_EXPRESSION_FLAGS_IGNORE_CASE
@@ -4107,6 +4629,11 @@ typedef struct pm_interpolated_regular_expression_node {
 /**
  * InterpolatedStringNode
  *
+ * Represents a string literal that contains interpolation.
+ *
+ *     "foo #{bar} baz"
+ *     ^^^^^^^^^^^^^^^^
+ *
  * Type: PM_INTERPOLATED_STRING_NODE
  * Flags:
  *    PM_INTERPOLATED_STRING_NODE_FLAGS_FROZEN
@@ -4137,6 +4664,11 @@ typedef struct pm_interpolated_string_node {
 /**
  * InterpolatedSymbolNode
  *
+ * Represents a symbol literal that contains interpolation.
+ *
+ *     :"foo #{bar} baz"
+ *     ^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_INTERPOLATED_SYMBOL_NODE
  *
  * @extends pm_node_t
@@ -4164,6 +4696,11 @@ typedef struct pm_interpolated_symbol_node {
 /**
  * InterpolatedXStringNode
  *
+ * Represents an xstring literal that contains interpolation.
+ *
+ *     `foo #{bar} baz`
+ *     ^^^^^^^^^^^^^^^^
+ *
  * Type: PM_INTERPOLATED_X_STRING_NODE
  *
  * @extends pm_node_t
@@ -4191,6 +4728,11 @@ typedef struct pm_interpolated_x_string_node {
 /**
  * ItLocalVariableReadNode
  *
+ * Represents reading from the implicit `it` local variable.
+ *
+ *     -> { it }
+ *          ^^
+ *
  * Type: PM_IT_LOCAL_VARIABLE_READ_NODE
  *
  * @extends pm_node_t
@@ -4203,6 +4745,11 @@ typedef struct pm_it_local_variable_read_node {
 /**
  * ItParametersNode
  *
+ * Represents an implicit set of parameters through the use of the `it` keyword within a block or lambda.
+ *
+ *     -> { it + it }
+ *     ^^^^^^^^^^^^^^
+ *
  * Type: PM_IT_PARAMETERS_NODE
  *
  * @extends pm_node_t
@@ -4215,6 +4762,11 @@ typedef struct pm_it_parameters_node {
 /**
  * KeywordHashNode
  *
+ * Represents a hash literal without opening and closing braces.
+ *
+ *     foo(a: b)
+ *         ^^^^
+ *
  * Type: PM_KEYWORD_HASH_NODE
  * Flags:
  *    PM_KEYWORD_HASH_NODE_FLAGS_SYMBOL_KEYS
@@ -4234,6 +4786,12 @@ typedef struct pm_keyword_hash_node {
 /**
  * KeywordRestParameterNode
  *
+ * Represents a keyword rest parameter to a method, block, or lambda definition.
+ *
+ *     def a(**b)
+ *           ^^^
+ *     end
+ *
  * Type: PM_KEYWORD_REST_PARAMETER_NODE
  * Flags:
  *    PM_PARAMETER_FLAGS_REPEATED_PARAMETER
@@ -4263,6 +4821,11 @@ typedef struct pm_keyword_rest_parameter_node {
 /**
  * LambdaNode
  *
+ * Represents using a lambda literal (not the lambda method call).
+ *
+ *     ->(value) { value * 2 }
+ *     ^^^^^^^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_LAMBDA_NODE
  *
  * @extends pm_node_t
@@ -4305,6 +4868,11 @@ typedef struct pm_lambda_node {
 /**
  * LocalVariableAndWriteNode
  *
+ * Represents the use of the `&&=` operator for assignment to a local variable.
+ *
+ *     target &&= value
+ *     ^^^^^^^^^^^^^^^^
+ *
  * Type: PM_LOCAL_VARIABLE_AND_WRITE_NODE
  *
  * @extends pm_node_t
@@ -4342,6 +4910,11 @@ typedef struct pm_local_variable_and_write_node {
 /**
  * LocalVariableOperatorWriteNode
  *
+ * Represents assigning to a local variable using an operator that isn't `=`.
+ *
+ *     target += value
+ *     ^^^^^^^^^^^^^^^
+ *
  * Type: PM_LOCAL_VARIABLE_OPERATOR_WRITE_NODE
  *
  * @extends pm_node_t
@@ -4384,6 +4957,11 @@ typedef struct pm_local_variable_operator_write_node {
 /**
  * LocalVariableOrWriteNode
  *
+ * Represents the use of the `||=` operator for assignment to a local variable.
+ *
+ *     target ||= value
+ *     ^^^^^^^^^^^^^^^^
+ *
  * Type: PM_LOCAL_VARIABLE_OR_WRITE_NODE
  *
  * @extends pm_node_t
@@ -4421,6 +4999,11 @@ typedef struct pm_local_variable_or_write_node {
 /**
  * LocalVariableReadNode
  *
+ * Represents reading a local variable. Note that this requires that a local variable of the same name has already been written to in the same scope, otherwise it is parsed as a method call.
+ *
+ *     foo
+ *     ^^^
+ *
  * Type: PM_LOCAL_VARIABLE_READ_NODE
  *
  * @extends pm_node_t
@@ -4461,6 +5044,11 @@ typedef struct pm_local_variable_read_node {
 /**
  * LocalVariableTargetNode
  *
+ * Represents writing to a local variable in a context that doesn't have an explicit value.
+ *
+ *     foo, bar = baz
+ *     ^^^  ^^^
+ *
  * Type: PM_LOCAL_VARIABLE_TARGET_NODE
  *
  * @extends pm_node_t
@@ -4483,6 +5071,11 @@ typedef struct pm_local_variable_target_node {
 /**
  * LocalVariableWriteNode
  *
+ * Represents writing to a local variable.
+ *
+ *     foo = 1
+ *     ^^^^^^^
+ *
  * Type: PM_LOCAL_VARIABLE_WRITE_NODE
  *
  * @extends pm_node_t
@@ -4556,6 +5149,11 @@ typedef struct pm_local_variable_write_node {
 /**
  * MatchLastLineNode
  *
+ * Represents a regular expression literal used in the predicate of a conditional to implicitly match against the last line read by an IO object.
+ *
+ *     if /foo/i then end
+ *        ^^^^^^
+ *
  * Type: PM_MATCH_LAST_LINE_NODE
  * Flags:
  *    PM_REGULAR_EXPRESSION_FLAGS_IGNORE_CASE
@@ -4600,6 +5198,11 @@ typedef struct pm_match_last_line_node {
 /**
  * MatchPredicateNode
  *
+ * Represents the use of the modifier `in` operator.
+ *
+ *     foo in bar
+ *     ^^^^^^^^^^
+ *
  * Type: PM_MATCH_PREDICATE_NODE
  *
  * @extends pm_node_t
@@ -4627,6 +5230,11 @@ typedef struct pm_match_predicate_node {
 /**
  * MatchRequiredNode
  *
+ * Represents the use of the `=>` operator.
+ *
+ *     foo => bar
+ *     ^^^^^^^^^^
+ *
  * Type: PM_MATCH_REQUIRED_NODE
  *
  * @extends pm_node_t
@@ -4654,6 +5262,11 @@ typedef struct pm_match_required_node {
 /**
  * MatchWriteNode
  *
+ * Represents writing local variables using a regular expression match with named capture groups.
+ *
+ *     /(?<foo>bar)/ =~ baz
+ *     ^^^^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_MATCH_WRITE_NODE
  *
  * @extends pm_node_t
@@ -4676,6 +5289,8 @@ typedef struct pm_match_write_node {
 /**
  * MissingNode
  *
+ * Represents a node that is missing from the source and results in a syntax error.
+ *
  * Type: PM_MISSING_NODE
  *
  * @extends pm_node_t
@@ -4688,6 +5303,11 @@ typedef struct pm_missing_node {
 /**
  * ModuleNode
  *
+ * Represents a module declaration involving the `module` keyword.
+ *
+ *     module Foo end
+ *     ^^^^^^^^^^^^^^
+ *
  * Type: PM_MODULE_NODE
  *
  * @extends pm_node_t
@@ -4730,6 +5350,16 @@ typedef struct pm_module_node {
 /**
  * MultiTargetNode
  *
+ * Represents a multi-target expression.
+ *
+ *     a, (b, c) = 1, 2, 3
+ *        ^^^^^^
+ *
+ * This can be a part of `MultiWriteNode` as above, or the target of a `for` loop
+ *
+ *     for a, b in [[1, 2], [3, 4]]
+ *         ^^^^
+ *
  * Type: PM_MULTI_TARGET_NODE
  *
  * @extends pm_node_t
@@ -4740,26 +5370,66 @@ typedef struct pm_multi_target_node {
 
     /**
      * MultiTargetNode#lefts
+     *
+     * Represents the targets expressions before a splat node.
+     *
+     *     a, (b, c, *) = 1, 2, 3, 4, 5
+     *         ^^^^
+     *
+     * The splat node can be absent, in that case all target expressions are in the left field.
+     *
+     *     a, (b, c) = 1, 2, 3, 4, 5
+     *         ^^^^
      */
     struct pm_node_list lefts;
 
     /**
      * MultiTargetNode#rest
+     *
+     * Represents a splat node in the target expression.
+     *
+     *     a, (b, *c) = 1, 2, 3, 4
+     *            ^^
+     *
+     * The variable can be empty, this results in a `SplatNode` with a `nil` expression field.
+     *
+     *     a, (b, *) = 1, 2, 3, 4
+     *            ^
+     *
+     * If the `*` is omitted, the field will containt an `ImplicitRestNode`
+     *
+     *     a, (b,) = 1, 2, 3, 4
+     *          ^
      */
     struct pm_node *rest;
 
     /**
      * MultiTargetNode#rights
+     *
+     * Represents the targets expressions after a splat node.
+     *
+     *     a, (*, b, c) = 1, 2, 3, 4, 5
+     *            ^^^^
      */
     struct pm_node_list rights;
 
     /**
      * MultiTargetNode#lparen_loc
+     *
+     * The location of the opening parenthesis.
+     *
+     *     a, (b, c) = 1, 2, 3
+     *        ^
      */
     pm_location_t lparen_loc;
 
     /**
      * MultiTargetNode#rparen_loc
+     *
+     * The location of the closing parenthesis.
+     *
+     *     a, (b, c) = 1, 2, 3
+     *             ^
      */
     pm_location_t rparen_loc;
 } pm_multi_target_node_t;
@@ -4767,6 +5437,11 @@ typedef struct pm_multi_target_node {
 /**
  * MultiWriteNode
  *
+ * Represents a write to a multi-target expression.
+ *
+ *     a, b, c = 1, 2, 3
+ *     ^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_MULTI_WRITE_NODE
  *
  * @extends pm_node_t
@@ -4777,36 +5452,86 @@ typedef struct pm_multi_write_node {
 
     /**
      * MultiWriteNode#lefts
+     *
+     * Represents the targets expressions before a splat node.
+     *
+     *     a, b, * = 1, 2, 3, 4, 5
+     *     ^^^^
+     *
+     * The splat node can be absent, in that case all target expressions are in the left field.
+     *
+     *     a, b, c = 1, 2, 3, 4, 5
+     *     ^^^^^^^
      */
     struct pm_node_list lefts;
 
     /**
      * MultiWriteNode#rest
+     *
+     * Represents a splat node in the target expression.
+     *
+     *     a, b, *c = 1, 2, 3, 4
+     *           ^^
+     *
+     * The variable can be empty, this results in a `SplatNode` with a `nil` expression field.
+     *
+     *     a, b, * = 1, 2, 3, 4
+     *           ^
+     *
+     * If the `*` is omitted, the field will containt an `ImplicitRestNode`
+     *
+     *     a, b, = 1, 2, 3, 4
+     *         ^
      */
     struct pm_node *rest;
 
     /**
      * MultiWriteNode#rights
+     *
+     * Represents the targets expressions after a splat node.
+     *
+     *     a, *, b, c = 1, 2, 3, 4, 5
+     *           ^^^^
      */
     struct pm_node_list rights;
 
     /**
      * MultiWriteNode#lparen_loc
+     *
+     * The location of the opening parenthesis.
+     *
+     *     (a, b, c) = 1, 2, 3
+     *     ^
      */
     pm_location_t lparen_loc;
 
     /**
      * MultiWriteNode#rparen_loc
+     *
+     * The location of the closing parenthesis.
+     *
+     *     (a, b, c) = 1, 2, 3
+     *             ^
      */
     pm_location_t rparen_loc;
 
     /**
      * MultiWriteNode#operator_loc
+     *
+     * The location of the operator.
+     *
+     *     a, b, c = 1, 2, 3
+     *             ^
      */
     pm_location_t operator_loc;
 
     /**
      * MultiWriteNode#value
+     *
+     * The value to write to the targets. It can be any [non-void expression](https://github.com/ruby/prism/blob/main/docs/parsing_rules.md#non-void-expression).
+     *
+     *     a, b, c = 1, 2, 3
+     *               ^^^^^^^
      */
     struct pm_node *value;
 } pm_multi_write_node_t;
@@ -4814,6 +5539,11 @@ typedef struct pm_multi_write_node {
 /**
  * NextNode
  *
+ * Represents the use of the `next` keyword.
+ *
+ *     next 1
+ *     ^^^^^^
+ *
  * Type: PM_NEXT_NODE
  *
  * @extends pm_node_t
@@ -4836,6 +5566,11 @@ typedef struct pm_next_node {
 /**
  * NilNode
  *
+ * Represents the use of the `nil` keyword.
+ *
+ *     nil
+ *     ^^^
+ *
  * Type: PM_NIL_NODE
  *
  * @extends pm_node_t
@@ -4848,6 +5583,12 @@ typedef struct pm_nil_node {
 /**
  * NoKeywordsParameterNode
  *
+ * Represents the use of `**nil` inside method arguments.
+ *
+ *     def a(**nil)
+ *           ^^^^^
+ *     end
+ *
  * Type: PM_NO_KEYWORDS_PARAMETER_NODE
  *
  * @extends pm_node_t
@@ -4870,6 +5611,11 @@ typedef struct pm_no_keywords_parameter_node {
 /**
  * NumberedParametersNode
  *
+ * Represents an implicit set of parameters through the use of numbered parameters within a block or lambda.
+ *
+ *     -> { _1 + _2 }
+ *     ^^^^^^^^^^^^^^
+ *
  * Type: PM_NUMBERED_PARAMETERS_NODE
  *
  * @extends pm_node_t
@@ -4887,6 +5633,11 @@ typedef struct pm_numbered_parameters_node {
 /**
  * NumberedReferenceReadNode
  *
+ * Represents reading a numbered reference to a capture in the previous match.
+ *
+ *     $1
+ *     ^^
+ *
  * Type: PM_NUMBERED_REFERENCE_READ_NODE
  *
  * @extends pm_node_t
@@ -4912,6 +5663,12 @@ typedef struct pm_numbered_reference_read_node {
 /**
  * OptionalKeywordParameterNode
  *
+ * Represents an optional keyword parameter to a method, block, or lambda definition.
+ *
+ *     def a(b: 1)
+ *           ^^^^
+ *     end
+ *
  * Type: PM_OPTIONAL_KEYWORD_PARAMETER_NODE
  * Flags:
  *    PM_PARAMETER_FLAGS_REPEATED_PARAMETER
@@ -4941,6 +5698,12 @@ typedef struct pm_optional_keyword_parameter_node {
 /**
  * OptionalParameterNode
  *
+ * Represents an optional parameter to a method, block, or lambda definition.
+ *
+ *     def a(b = 1)
+ *           ^^^^^
+ *     end
+ *
  * Type: PM_OPTIONAL_PARAMETER_NODE
  * Flags:
  *    PM_PARAMETER_FLAGS_REPEATED_PARAMETER
@@ -4975,6 +5738,11 @@ typedef struct pm_optional_parameter_node {
 /**
  * OrNode
  *
+ * Represents the use of the `||` operator or the `or` keyword.
+ *
+ *     left or right
+ *     ^^^^^^^^^^^^^
+ *
  * Type: PM_OR_NODE
  *
  * @extends pm_node_t
@@ -5023,6 +5791,12 @@ typedef struct pm_or_node {
 /**
  * ParametersNode
  *
+ * Represents the list of parameters on a method, block, or lambda definition.
+ *
+ *     def a(b, c, d)
+ *           ^^^^^^^
+ *     end
+ *
  * Type: PM_PARAMETERS_NODE
  *
  * @extends pm_node_t
@@ -5070,6 +5844,11 @@ typedef struct pm_parameters_node {
 /**
  * ParenthesesNode
  *
+ * Represents a parenthesized expression
+ *
+ *     (10 + 34)
+ *     ^^^^^^^^^
+ *
  * Type: PM_PARENTHESES_NODE
  *
  * @extends pm_node_t
@@ -5097,6 +5876,11 @@ typedef struct pm_parentheses_node {
 /**
  * PinnedExpressionNode
  *
+ * Represents the use of the `^` operator for pinning an expression in a pattern matching expression.
+ *
+ *     foo in ^(bar)
+ *            ^^^^^^
+ *
  * Type: PM_PINNED_EXPRESSION_NODE
  *
  * @extends pm_node_t
@@ -5129,6 +5913,11 @@ typedef struct pm_pinned_expression_node {
 /**
  * PinnedVariableNode
  *
+ * Represents the use of the `^` operator for pinning a variable in a pattern matching expression.
+ *
+ *     foo in ^bar
+ *            ^^^^
+ *
  * Type: PM_PINNED_VARIABLE_NODE
  *
  * @extends pm_node_t
@@ -5151,6 +5940,11 @@ typedef struct pm_pinned_variable_node {
 /**
  * PostExecutionNode
  *
+ * Represents the use of the `END` keyword.
+ *
+ *     END { foo }
+ *     ^^^^^^^^^^^
+ *
  * Type: PM_POST_EXECUTION_NODE
  *
  * @extends pm_node_t
@@ -5183,6 +5977,11 @@ typedef struct pm_post_execution_node {
 /**
  * PreExecutionNode
  *
+ * Represents the use of the `BEGIN` keyword.
+ *
+ *     BEGIN { foo }
+ *     ^^^^^^^^^^^^^
+ *
  * Type: PM_PRE_EXECUTION_NODE
  *
  * @extends pm_node_t
@@ -5215,6 +6014,8 @@ typedef struct pm_pre_execution_node {
 /**
  * ProgramNode
  *
+ * The top level node of any parse tree.
+ *
  * Type: PM_PROGRAM_NODE
  *
  * @extends pm_node_t
@@ -5237,6 +6038,14 @@ typedef struct pm_program_node {
 /**
  * RangeNode
  *
+ * Represents the use of the `..` or `...` operators.
+ *
+ *     1..2
+ *     ^^^^
+ *
+ *     c if a =~ /left/ ... b =~ /right/
+ *          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_RANGE_NODE
  * Flags:
  *    PM_RANGE_FLAGS_EXCLUDE_END
@@ -5285,6 +6094,11 @@ typedef struct pm_range_node {
 /**
  * RationalNode
  *
+ * Represents a rational number literal.
+ *
+ *     1.0r
+ *     ^^^^
+ *
  * Type: PM_RATIONAL_NODE
  * Flags:
  *    PM_INTEGER_BASE_FLAGS_BINARY
@@ -5320,6 +6134,11 @@ typedef struct pm_rational_node {
 /**
  * RedoNode
  *
+ * Represents the use of the `redo` keyword.
+ *
+ *     redo
+ *     ^^^^
+ *
  * Type: PM_REDO_NODE
  *
  * @extends pm_node_t
@@ -5332,6 +6151,11 @@ typedef struct pm_redo_node {
 /**
  * RegularExpressionNode
  *
+ * Represents a regular expression literal with no interpolation.
+ *
+ *     /foo/i
+ *     ^^^^^^
+ *
  * Type: PM_REGULAR_EXPRESSION_NODE
  * Flags:
  *    PM_REGULAR_EXPRESSION_FLAGS_IGNORE_CASE
@@ -5376,6 +6200,12 @@ typedef struct pm_regular_expression_node {
 /**
  * RequiredKeywordParameterNode
  *
+ * Represents a required keyword parameter to a method, block, or lambda definition.
+ *
+ *     def a(b: )
+ *           ^^
+ *     end
+ *
  * Type: PM_REQUIRED_KEYWORD_PARAMETER_NODE
  * Flags:
  *    PM_PARAMETER_FLAGS_REPEATED_PARAMETER
@@ -5400,6 +6230,12 @@ typedef struct pm_required_keyword_parameter_node {
 /**
  * RequiredParameterNode
  *
+ * Represents a required parameter to a method, block, or lambda definition.
+ *
+ *     def a(b)
+ *           ^
+ *     end
+ *
  * Type: PM_REQUIRED_PARAMETER_NODE
  * Flags:
  *    PM_PARAMETER_FLAGS_REPEATED_PARAMETER
@@ -5419,6 +6255,11 @@ typedef struct pm_required_parameter_node {
 /**
  * RescueModifierNode
  *
+ * Represents an expression modified with a rescue.
+ *
+ *     foo rescue nil
+ *     ^^^^^^^^^^^^^^
+ *
  * Type: PM_RESCUE_MODIFIER_NODE
  *
  * @extends pm_node_t
@@ -5446,6 +6287,16 @@ typedef struct pm_rescue_modifier_node {
 /**
  * RescueNode
  *
+ * Represents a rescue statement.
+ *
+ *     begin
+ *     rescue Foo, *splat, Bar => ex
+ *       foo
+ *     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ *     end
+ *
+ * `Foo, *splat, Bar` are in the `exceptions` field. `ex` is in the `exception` field.
+ *
  * Type: PM_RESCUE_NODE
  *
  * @extends pm_node_t
@@ -5480,14 +6331,20 @@ typedef struct pm_rescue_node {
     struct pm_statements_node *statements;
 
     /**
-     * RescueNode#consequent
+     * RescueNode#subsequent
      */
-    struct pm_rescue_node *consequent;
+    struct pm_rescue_node *subsequent;
 } pm_rescue_node_t;
 
 /**
  * RestParameterNode
  *
+ * Represents a rest parameter to a method, block, or lambda definition.
+ *
+ *     def a(*b)
+ *           ^^
+ *     end
+ *
  * Type: PM_REST_PARAMETER_NODE
  * Flags:
  *    PM_PARAMETER_FLAGS_REPEATED_PARAMETER
@@ -5517,6 +6374,11 @@ typedef struct pm_rest_parameter_node {
 /**
  * RetryNode
  *
+ * Represents the use of the `retry` keyword.
+ *
+ *     retry
+ *     ^^^^^
+ *
  * Type: PM_RETRY_NODE
  *
  * @extends pm_node_t
@@ -5529,9 +6391,12 @@ typedef struct pm_retry_node {
 /**
  * ReturnNode
  *
+ * Represents the use of the `return` keyword.
+ *
+ *     return 1
+ *     ^^^^^^^^
+ *
  * Type: PM_RETURN_NODE
- * Flags:
- *    PM_RETURN_NODE_FLAGS_REDUNDANT
  *
  * @extends pm_node_t
  */
@@ -5553,6 +6418,11 @@ typedef struct pm_return_node {
 /**
  * SelfNode
  *
+ * Represents the `self` keyword.
+ *
+ *     self
+ *     ^^^^
+ *
  * Type: PM_SELF_NODE
  *
  * @extends pm_node_t
@@ -5565,6 +6435,12 @@ typedef struct pm_self_node {
 /**
  * ShareableConstantNode
  *
+ * This node wraps a constant write to indicate that when the value is written, it should have its shareability state modified.
+ *
+ *     # shareable_constant_value: literal
+ *     C = { a: 1 }
+ *     ^^^^^^^^^^^^
+ *
  * Type: PM_SHAREABLE_CONSTANT_NODE
  * Flags:
  *    PM_SHAREABLE_CONSTANT_NODE_FLAGS_LITERAL
@@ -5588,6 +6464,11 @@ typedef struct pm_shareable_constant_node {
 /**
  * SingletonClassNode
  *
+ * Represents a singleton class declaration involving the `class` keyword.
+ *
+ *     class << self end
+ *     ^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_SINGLETON_CLASS_NODE
  *
  * @extends pm_node_t
@@ -5630,6 +6511,11 @@ typedef struct pm_singleton_class_node {
 /**
  * SourceEncodingNode
  *
+ * Represents the use of the `__ENCODING__` keyword.
+ *
+ *     __ENCODING__
+ *     ^^^^^^^^^^^^
+ *
  * Type: PM_SOURCE_ENCODING_NODE
  *
  * @extends pm_node_t
@@ -5642,6 +6528,11 @@ typedef struct pm_source_encoding_node {
 /**
  * SourceFileNode
  *
+ * Represents the use of the `__FILE__` keyword.
+ *
+ *     __FILE__
+ *     ^^^^^^^^
+ *
  * Type: PM_SOURCE_FILE_NODE
  * Flags:
  *    PM_STRING_FLAGS_FORCED_UTF8_ENCODING
@@ -5666,6 +6557,11 @@ typedef struct pm_source_file_node {
 /**
  * SourceLineNode
  *
+ * Represents the use of the `__LINE__` keyword.
+ *
+ *     __LINE__
+ *     ^^^^^^^^
+ *
  * Type: PM_SOURCE_LINE_NODE
  *
  * @extends pm_node_t
@@ -5678,6 +6574,11 @@ typedef struct pm_source_line_node {
 /**
  * SplatNode
  *
+ * Represents the use of the splat operator.
+ *
+ *     [*a]
+ *      ^^
+ *
  * Type: PM_SPLAT_NODE
  *
  * @extends pm_node_t
@@ -5700,6 +6601,11 @@ typedef struct pm_splat_node {
 /**
  * StatementsNode
  *
+ * Represents a set of statements contained within some scope.
+ *
+ *     foo; bar; baz
+ *     ^^^^^^^^^^^^^
+ *
  * Type: PM_STATEMENTS_NODE
  *
  * @extends pm_node_t
@@ -5717,6 +6623,17 @@ typedef struct pm_statements_node {
 /**
  * StringNode
  *
+ * Represents a string literal, a string contained within a `%w` list, or plain string content within an interpolated string.
+ *
+ *     "foo"
+ *     ^^^^^
+ *
+ *     %w[foo]
+ *        ^^^
+ *
+ *     "foo #{bar} baz"
+ *      ^^^^      ^^^^
+ *
  * Type: PM_STRING_NODE
  * Flags:
  *    PM_STRING_FLAGS_FORCED_UTF8_ENCODING
@@ -5754,6 +6671,14 @@ typedef struct pm_string_node {
 /**
  * SuperNode
  *
+ * Represents the use of the `super` keyword with parentheses or arguments.
+ *
+ *     super()
+ *     ^^^^^^^
+ *
+ *     super foo, bar
+ *     ^^^^^^^^^^^^^^
+ *
  * Type: PM_SUPER_NODE
  *
  * @extends pm_node_t
@@ -5791,6 +6716,14 @@ typedef struct pm_super_node {
 /**
  * SymbolNode
  *
+ * Represents a symbol literal or a symbol contained within a `%i` list.
+ *
+ *     :foo
+ *     ^^^^
+ *
+ *     %i[foo]
+ *        ^^^
+ *
  * Type: PM_SYMBOL_NODE
  * Flags:
  *    PM_SYMBOL_FLAGS_FORCED_UTF8_ENCODING
@@ -5827,6 +6760,11 @@ typedef struct pm_symbol_node {
 /**
  * TrueNode
  *
+ * Represents the use of the literal `true` keyword.
+ *
+ *     true
+ *     ^^^^
+ *
  * Type: PM_TRUE_NODE
  *
  * @extends pm_node_t
@@ -5839,6 +6777,11 @@ typedef struct pm_true_node {
 /**
  * UndefNode
  *
+ * Represents the use of the `undef` keyword.
+ *
+ *     undef :foo, :bar, :baz
+ *     ^^^^^^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_UNDEF_NODE
  *
  * @extends pm_node_t
@@ -5861,6 +6804,14 @@ typedef struct pm_undef_node {
 /**
  * UnlessNode
  *
+ * Represents the use of the `unless` keyword, either in the block form or the modifier form.
+ *
+ *     bar unless foo
+ *     ^^^^^^^^^^^^^^
+ *
+ *     unless foo then bar end
+ *     ^^^^^^^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_UNLESS_NODE
  *
  * @extends pm_node_t
@@ -5917,14 +6868,14 @@ typedef struct pm_unless_node {
     struct pm_statements_node *statements;
 
     /**
-     * UnlessNode#consequent
+     * UnlessNode#else_clause
      *
      * The else clause of the unless expression, if present.
      *
      *     unless cond then bar else baz end
      *                          ^^^^^^^^
      */
-    struct pm_else_node *consequent;
+    struct pm_else_node *else_clause;
 
     /**
      * UnlessNode#end_keyword_loc
@@ -5940,6 +6891,14 @@ typedef struct pm_unless_node {
 /**
  * UntilNode
  *
+ * Represents the use of the `until` keyword, either in the block form or the modifier form.
+ *
+ *     bar until foo
+ *     ^^^^^^^^^^^^^
+ *
+ *     until foo do bar end
+ *     ^^^^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_UNTIL_NODE
  * Flags:
  *    PM_LOOP_FLAGS_BEGIN_MODIFIER
@@ -5974,6 +6933,13 @@ typedef struct pm_until_node {
 /**
  * WhenNode
  *
+ * Represents the use of the `when` keyword within a case statement.
+ *
+ *     case true
+ *     when true
+ *     ^^^^^^^^^
+ *     end
+ *
  * Type: PM_WHEN_NODE
  *
  * @extends pm_node_t
@@ -6006,6 +6972,14 @@ typedef struct pm_when_node {
 /**
  * WhileNode
  *
+ * Represents the use of the `while` keyword, either in the block form or the modifier form.
+ *
+ *     bar while foo
+ *     ^^^^^^^^^^^^^
+ *
+ *     while foo do bar end
+ *     ^^^^^^^^^^^^^^^^^^^^
+ *
  * Type: PM_WHILE_NODE
  * Flags:
  *    PM_LOOP_FLAGS_BEGIN_MODIFIER
@@ -6040,6 +7014,11 @@ typedef struct pm_while_node {
 /**
  * XStringNode
  *
+ * Represents an xstring literal with no interpolation.
+ *
+ *     `foo`
+ *     ^^^^^
+ *
  * Type: PM_X_STRING_NODE
  * Flags:
  *    PM_ENCODING_FLAGS_FORCED_UTF8_ENCODING
@@ -6075,6 +7054,11 @@ typedef struct pm_x_string_node {
 /**
  * YieldNode
  *
+ * Represents the use of the `yield` keyword.
+ *
+ *     yield 1
+ *     ^^^^^^^
+ *
  * Type: PM_YIELD_NODE
  *
  * @extends pm_node_t
@@ -6109,10 +7093,13 @@ typedef struct pm_yield_node {
  */
 typedef enum pm_arguments_node_flags {
     /** if arguments contain keywords */
-    PM_ARGUMENTS_NODE_FLAGS_CONTAINS_KEYWORDS = 1,
+    PM_ARGUMENTS_NODE_FLAGS_CONTAINS_KEYWORDS = 4,
 
     /** if arguments contain keyword splat */
-    PM_ARGUMENTS_NODE_FLAGS_CONTAINS_KEYWORD_SPLAT = 2,
+    PM_ARGUMENTS_NODE_FLAGS_CONTAINS_KEYWORD_SPLAT = 8,
+
+    /** if arguments contain splat */
+    PM_ARGUMENTS_NODE_FLAGS_CONTAINS_SPLAT = 16,
 } pm_arguments_node_flags_t;
 
 /**
@@ -6120,7 +7107,7 @@ typedef enum pm_arguments_node_flags {
  */
 typedef enum pm_array_node_flags {
     /** if array contains splat nodes */
-    PM_ARRAY_NODE_FLAGS_CONTAINS_SPLAT = 1,
+    PM_ARRAY_NODE_FLAGS_CONTAINS_SPLAT = 4,
 } pm_array_node_flags_t;
 
 /**
@@ -6128,16 +7115,16 @@ typedef enum pm_array_node_flags {
  */
 typedef enum pm_call_node_flags {
     /** &. operator */
-    PM_CALL_NODE_FLAGS_SAFE_NAVIGATION = 1,
+    PM_CALL_NODE_FLAGS_SAFE_NAVIGATION = 4,
 
     /** a call that could have been a local variable */
-    PM_CALL_NODE_FLAGS_VARIABLE_CALL = 2,
+    PM_CALL_NODE_FLAGS_VARIABLE_CALL = 8,
 
     /** a call that is an attribute write, so the value being written should be returned */
-    PM_CALL_NODE_FLAGS_ATTRIBUTE_WRITE = 4,
+    PM_CALL_NODE_FLAGS_ATTRIBUTE_WRITE = 16,
 
     /** a call that ignores method visibility */
-    PM_CALL_NODE_FLAGS_IGNORE_VISIBILITY = 8,
+    PM_CALL_NODE_FLAGS_IGNORE_VISIBILITY = 32,
 } pm_call_node_flags_t;
 
 /**
@@ -6145,10 +7132,10 @@ typedef enum pm_call_node_flags {
  */
 typedef enum pm_encoding_flags {
     /** internal bytes forced the encoding to UTF-8 */
-    PM_ENCODING_FLAGS_FORCED_UTF8_ENCODING = 1,
+    PM_ENCODING_FLAGS_FORCED_UTF8_ENCODING = 4,
 
     /** internal bytes forced the encoding to binary */
-    PM_ENCODING_FLAGS_FORCED_BINARY_ENCODING = 2,
+    PM_ENCODING_FLAGS_FORCED_BINARY_ENCODING = 8,
 } pm_encoding_flags_t;
 
 /**
@@ -6156,16 +7143,16 @@ typedef enum pm_encoding_flags {
  */
 typedef enum pm_integer_base_flags {
     /** 0b prefix */
-    PM_INTEGER_BASE_FLAGS_BINARY = 1,
+    PM_INTEGER_BASE_FLAGS_BINARY = 4,
 
     /** 0d or no prefix */
-    PM_INTEGER_BASE_FLAGS_DECIMAL = 2,
+    PM_INTEGER_BASE_FLAGS_DECIMAL = 8,
 
     /** 0o or 0 prefix */
-    PM_INTEGER_BASE_FLAGS_OCTAL = 4,
+    PM_INTEGER_BASE_FLAGS_OCTAL = 16,
 
     /** 0x prefix */
-    PM_INTEGER_BASE_FLAGS_HEXADECIMAL = 8,
+    PM_INTEGER_BASE_FLAGS_HEXADECIMAL = 32,
 } pm_integer_base_flags_t;
 
 /**
@@ -6173,10 +7160,10 @@ typedef enum pm_integer_base_flags {
  */
 typedef enum pm_interpolated_string_node_flags {
     /** frozen by virtue of a `frozen_string_literal: true` comment or `--enable-frozen-string-literal`; only for adjacent string literals like `'a' 'b'` */
-    PM_INTERPOLATED_STRING_NODE_FLAGS_FROZEN = 1,
+    PM_INTERPOLATED_STRING_NODE_FLAGS_FROZEN = 4,
 
     /** mutable by virtue of a `frozen_string_literal: false` comment or `--disable-frozen-string-literal`; only for adjacent string literals like `'a' 'b'` */
-    PM_INTERPOLATED_STRING_NODE_FLAGS_MUTABLE = 2,
+    PM_INTERPOLATED_STRING_NODE_FLAGS_MUTABLE = 8,
 } pm_interpolated_string_node_flags_t;
 
 /**
@@ -6184,7 +7171,7 @@ typedef enum pm_interpolated_string_node_flags {
  */
 typedef enum pm_keyword_hash_node_flags {
     /** a keyword hash which only has `AssocNode` elements all with symbol keys, which means the elements can be treated as keyword arguments */
-    PM_KEYWORD_HASH_NODE_FLAGS_SYMBOL_KEYS = 1,
+    PM_KEYWORD_HASH_NODE_FLAGS_SYMBOL_KEYS = 4,
 } pm_keyword_hash_node_flags_t;
 
 /**
@@ -6192,7 +7179,7 @@ typedef enum pm_keyword_hash_node_flags {
  */
 typedef enum pm_loop_flags {
     /** a loop after a begin statement, so the body is executed first before the condition */
-    PM_LOOP_FLAGS_BEGIN_MODIFIER = 1,
+    PM_LOOP_FLAGS_BEGIN_MODIFIER = 4,
 } pm_loop_flags_t;
 
 /**
@@ -6200,7 +7187,7 @@ typedef enum pm_loop_flags {
  */
 typedef enum pm_parameter_flags {
     /** a parameter name that has been repeated in the method signature */
-    PM_PARAMETER_FLAGS_REPEATED_PARAMETER = 1,
+    PM_PARAMETER_FLAGS_REPEATED_PARAMETER = 4,
 } pm_parameter_flags_t;
 
 /**
@@ -6208,7 +7195,7 @@ typedef enum pm_parameter_flags {
  */
 typedef enum pm_range_flags {
     /** ... operator */
-    PM_RANGE_FLAGS_EXCLUDE_END = 1,
+    PM_RANGE_FLAGS_EXCLUDE_END = 4,
 } pm_range_flags_t;
 
 /**
@@ -6216,59 +7203,51 @@ typedef enum pm_range_flags {
  */
 typedef enum pm_regular_expression_flags {
     /** i - ignores the case of characters when matching */
-    PM_REGULAR_EXPRESSION_FLAGS_IGNORE_CASE = 1,
+    PM_REGULAR_EXPRESSION_FLAGS_IGNORE_CASE = 4,
 
     /** x - ignores whitespace and allows comments in regular expressions */
-    PM_REGULAR_EXPRESSION_FLAGS_EXTENDED = 2,
+    PM_REGULAR_EXPRESSION_FLAGS_EXTENDED = 8,
 
     /** m - allows $ to match the end of lines within strings */
-    PM_REGULAR_EXPRESSION_FLAGS_MULTI_LINE = 4,
+    PM_REGULAR_EXPRESSION_FLAGS_MULTI_LINE = 16,
 
     /** o - only interpolates values into the regular expression once */
-    PM_REGULAR_EXPRESSION_FLAGS_ONCE = 8,
+    PM_REGULAR_EXPRESSION_FLAGS_ONCE = 32,
 
     /** e - forces the EUC-JP encoding */
-    PM_REGULAR_EXPRESSION_FLAGS_EUC_JP = 16,
+    PM_REGULAR_EXPRESSION_FLAGS_EUC_JP = 64,
 
     /** n - forces the ASCII-8BIT encoding */
-    PM_REGULAR_EXPRESSION_FLAGS_ASCII_8BIT = 32,
+    PM_REGULAR_EXPRESSION_FLAGS_ASCII_8BIT = 128,
 
     /** s - forces the Windows-31J encoding */
-    PM_REGULAR_EXPRESSION_FLAGS_WINDOWS_31J = 64,
+    PM_REGULAR_EXPRESSION_FLAGS_WINDOWS_31J = 256,
 
     /** u - forces the UTF-8 encoding */
-    PM_REGULAR_EXPRESSION_FLAGS_UTF_8 = 128,
+    PM_REGULAR_EXPRESSION_FLAGS_UTF_8 = 512,
 
     /** internal bytes forced the encoding to UTF-8 */
-    PM_REGULAR_EXPRESSION_FLAGS_FORCED_UTF8_ENCODING = 256,
+    PM_REGULAR_EXPRESSION_FLAGS_FORCED_UTF8_ENCODING = 1024,
 
     /** internal bytes forced the encoding to binary */
-    PM_REGULAR_EXPRESSION_FLAGS_FORCED_BINARY_ENCODING = 512,
+    PM_REGULAR_EXPRESSION_FLAGS_FORCED_BINARY_ENCODING = 2048,
 
     /** internal bytes forced the encoding to US-ASCII */
-    PM_REGULAR_EXPRESSION_FLAGS_FORCED_US_ASCII_ENCODING = 1024,
+    PM_REGULAR_EXPRESSION_FLAGS_FORCED_US_ASCII_ENCODING = 4096,
 } pm_regular_expression_flags_t;
 
-/**
- * Flags for return nodes.
- */
-typedef enum pm_return_node_flags {
-    /** a return statement that is redundant because it is the last statement in a method */
-    PM_RETURN_NODE_FLAGS_REDUNDANT = 1,
-} pm_return_node_flags_t;
-
 /**
  * Flags for shareable constant nodes.
  */
 typedef enum pm_shareable_constant_node_flags {
     /** constant writes that should be modified with shareable constant value literal */
-    PM_SHAREABLE_CONSTANT_NODE_FLAGS_LITERAL = 1,
+    PM_SHAREABLE_CONSTANT_NODE_FLAGS_LITERAL = 4,
 
     /** constant writes that should be modified with shareable constant value experimental everything */
-    PM_SHAREABLE_CONSTANT_NODE_FLAGS_EXPERIMENTAL_EVERYTHING = 2,
+    PM_SHAREABLE_CONSTANT_NODE_FLAGS_EXPERIMENTAL_EVERYTHING = 8,
 
     /** constant writes that should be modified with shareable constant value experimental copy */
-    PM_SHAREABLE_CONSTANT_NODE_FLAGS_EXPERIMENTAL_COPY = 4,
+    PM_SHAREABLE_CONSTANT_NODE_FLAGS_EXPERIMENTAL_COPY = 16,
 } pm_shareable_constant_node_flags_t;
 
 /**
@@ -6276,16 +7255,16 @@ typedef enum pm_shareable_constant_node_flags {
  */
 typedef enum pm_string_flags {
     /** internal bytes forced the encoding to UTF-8 */
-    PM_STRING_FLAGS_FORCED_UTF8_ENCODING = 1,
+    PM_STRING_FLAGS_FORCED_UTF8_ENCODING = 4,
 
     /** internal bytes forced the encoding to binary */
-    PM_STRING_FLAGS_FORCED_BINARY_ENCODING = 2,
+    PM_STRING_FLAGS_FORCED_BINARY_ENCODING = 8,
 
     /** frozen by virtue of a `frozen_string_literal: true` comment or `--enable-frozen-string-literal` */
-    PM_STRING_FLAGS_FROZEN = 4,
+    PM_STRING_FLAGS_FROZEN = 16,
 
     /** mutable by virtue of a `frozen_string_literal: false` comment or `--disable-frozen-string-literal` */
-    PM_STRING_FLAGS_MUTABLE = 8,
+    PM_STRING_FLAGS_MUTABLE = 32,
 } pm_string_flags_t;
 
 /**
@@ -6293,13 +7272,13 @@ typedef enum pm_string_flags {
  */
 typedef enum pm_symbol_flags {
     /** internal bytes forced the encoding to UTF-8 */
-    PM_SYMBOL_FLAGS_FORCED_UTF8_ENCODING = 1,
+    PM_SYMBOL_FLAGS_FORCED_UTF8_ENCODING = 4,
 
     /** internal bytes forced the encoding to binary */
-    PM_SYMBOL_FLAGS_FORCED_BINARY_ENCODING = 2,
+    PM_SYMBOL_FLAGS_FORCED_BINARY_ENCODING = 8,
 
     /** internal bytes forced the encoding to US-ASCII */
-    PM_SYMBOL_FLAGS_FORCED_US_ASCII_ENCODING = 4,
+    PM_SYMBOL_FLAGS_FORCED_US_ASCII_ENCODING = 16,
 } pm_symbol_flags_t;
 
 /**