From 5f7e4ba2204e6aa59a59525be877d94f57f5a763 Mon Sep 17 00:00:00 2001
From: Benoit Daloze <eregontp@gmail.com>
Date: Thu, 25 Jul 2024 22:49:42 +0200
Subject: [PATCH] WIP: Review config.yml: documentation, types and field names

---
 config.yml | 41 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 37 insertions(+), 4 deletions(-)

diff --git a/config.yml b/config.yml
index fed82651732..2b6fee3a899 100644
--- a/config.yml
+++ b/config.yml
@@ -770,15 +770,25 @@ nodes:
     fields:
       - name: new_name
         type: node
+        kind:
+          - GlobalVariableReadNode
+          - BackReferenceReadNode
+          - NumberedReferenceReadNode
         comment: |
-          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
                     ^^^^
       - name: old_name
         type: node
+        kind:
+          - GlobalVariableReadNode
+          - BackReferenceReadNode
+          - NumberedReferenceReadNode
+          - SymbolNode # On parsing error of `alias $a b`
+          - MissingNode # On parsing error of `alias $a 42`
         comment: |
-          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
                          ^^^^
@@ -798,8 +808,16 @@ nodes:
     fields:
       - name: new_name
         type: node
+        kind:
+          - SymbolNode
+          - InterpolatedSymbolNode
       - name: old_name
         type: node
+        kind:
+          - SymbolNode
+          - InterpolatedSymbolNode
+          - GlobalVariableReadNode # On parsing error of `alias a $b`
+          - MissingNode # On parsing error of `alias a 42`
       - name: keyword_loc
         type: location
     comment: |
@@ -897,6 +915,9 @@ nodes:
     fields:
       - name: constant
         type: node?
+      # TODO requireds seems not symmetric with posts, maybe it could be pre/rest/post?
+      # Also posts are also required, so requireds seems not a great name.
+      # Somewhat related: https://github.com/ruby/prism/issues/1600
       - name: requireds
         type: node[]
       - name: rest
@@ -1030,7 +1051,7 @@ nodes:
       - name: operator_loc
         type: location
     comment: |
-      Represents block method arguments.
+      Represents a block argument using `&`.
 
           bar(&args)
           ^^^^^^^^^^
@@ -1050,8 +1071,15 @@ nodes:
         type: constant[]
       - name: parameters
         type: node?
+        kind:
+          - BlockParametersNode
+          - NumberedParametersNode
+          - ItParametersNode
       - name: body
         type: node?
+        kind:
+          - StatementsNode
+          - BeginNode
       - name: opening_loc
         type: location
       - name: closing_loc
@@ -1071,7 +1099,7 @@ nodes:
       - name: operator_loc
         type: location
     comment: |
-      Represents a block parameter to a method, block, or lambda definition.
+      Represents a block parameter of a method, block, or lambda definition.
 
           def a(&b)
                 ^^
@@ -2158,8 +2186,13 @@ nodes:
                 baz
                 ^^^
               end
+      # TODO: consequent should mean then_clause in logic, but it's actually else_clause here.
+      # BTW, BeginNode has a `else_clause` field, maybe a good name for this?
       - name: consequent
         type: node?
+        kind:
+          - ElseNode
+          - IfNode
         comment: |
           Represents an `ElseNode` or an `IfNode` when there is an `else` or an `elsif` in the `if` statement.