update code documentation

crates/core/src/ast/traversal/visitor.rs

@@ -5,14 +5,14 @@ use super::contexts::*;
 
 
 /// Handle visitations to expression nodes.
-/// Nodes that contain visitable children nodes inside them have a corresponding `exit_` function,
-/// which is run after the node itself and its children are visited.
+/// Visitor functions for nodes that contain visitable children nodes inside them return traversal policy objects that dictate if those children are traversed into.
+/// By default all policy fields have `true` value.
+/// These nodes also have a corresponding `exit_` function for them, which is run after the node itself and (possibly) its children are visited.
 #[allow(unused_variables)]
 pub trait ExpressionVisitor {
     /// Called when visiting a parenthesized expression node.
-    /// Should return whether to traverse into the expression [nested][NestedExpressionNode::inner] inside it. True by default.
     fn visit_nested_expr(&mut self, n: &NestedExpressionNode, ctx: ExpressionTraversalContext) -> NestedExpressionTraversalPolicy { Default::default() }
-    /// Called after visiting the nested expression node and possibly its [inner][NestedExpressionNode::inner] node.
+    /// Called after visiting the nested expression node and possibly also children nodes specified in traversal policy.
     fn exit_nested_expr(&mut self, n: &NestedExpressionNode, ctx: ExpressionTraversalContext) {}
 
     /// Called when visiting a node representing any literal.
@@ -34,118 +34,86 @@ pub trait ExpressionVisitor {
     fn visit_identifier_expr(&mut self, n: &IdentifierNode, ctx: ExpressionTraversalContext) {}
 
     /// Called when visiting a function call node.
-    /// Should return whether to traverse into this node's callee [func][FunctionCallExpressionNode::func] node 
-    /// and [args][FunctionCallExpressionNode::args]. Both true by default.
     fn visit_func_call_expr(&mut self, n: &FunctionCallExpressionNode, ctx: ExpressionTraversalContext) -> FunctionCallExpressionTraversalPolicy { Default::default() }
-    /// Called after visiting function call expression node and possibly its [func][FunctionCallExpressionNode::func] and [args][FunctionCallExpressionNode::args] nodes.
+    /// Called after visiting function call expression node and possibly also children nodes specified in traversal policy.
     fn exit_func_call_expr(&mut self, n: &FunctionCallExpressionNode, ctx: ExpressionTraversalContext) {}
 
     /// Called when visiting a function call argument.
     /// Node may be None due to it referring to an optional function parameter.
-    /// Should return whether to traverse into the expression that this argument contains unless said argument was omitted. True by default.
     fn visit_func_call_arg(&mut self, n: &FunctionCallArgument) -> FunctionCallArgumentTraversalPolicy { Default::default() }
-    /// Called after visiting function call argument and possibly also the expression that it represents.
+    /// Called after visiting function call argument and possibly also children nodes specified in traversal policy.
     fn exit_func_call_arg(&mut self, n: &FunctionCallArgument) {}
 
     /// Called when visiting an indexing expression.
-    /// Should return whether to traverse into this node's [accessor][ArrayExpressionNode::accessor] 
-    /// and [index][ArrayExpressionNode::index] expressions. Both true by default.
     fn visit_array_expr(&mut self, n: &ArrayExpressionNode, ctx: ExpressionTraversalContext) -> ArrayExpressionTraversalPolicy { Default::default() }
-    /// Called after visiting an indexing expression and possibly its [accessor][ArrayExpressionNode::accessor] 
-    /// and [index][ArrayExpressionNode::index] expressions.
+    /// Called after visiting an indexing expression and possibly also children nodes specified in traversal policy.
     fn exit_array_expr(&mut self, n: &ArrayExpressionNode, ctx: ExpressionTraversalContext) {}
 
     /// Called when visiting an expression of accessing a field in an object.
-    /// Should return whether to traverse into this node's [accessor][MemberFieldExpressionNode::accessor] node. True by default.
-    /// The [member][MemberFieldExpressionNode::member] identifier node is not visited automatically.
     fn visit_member_field_expr(&mut self, n: &MemberFieldExpressionNode, ctx: ExpressionTraversalContext) -> MemberFieldExpressionTraversalPolicy { Default::default() }
-    /// Called after visiting an expression of accessing a field in an object and possibly its
-    /// [accessor][MemberFieldExpressionNode::accessor]  and [member][MemberFieldExpressionNode::member] nodes.
+    /// Called after visiting an expression of accessing a field in an object and possibly also children nodes specified in traversal policy.
     fn exit_member_field_expr(&mut self, n: &MemberFieldExpressionNode, ctx: ExpressionTraversalContext) {}
 
     /// Called when visiting an instantiation expression.
-    /// Should return whether to traverse into this node's [lifetime_obj][NewExpressionNode::lifetime_obj] node if there is any. True by default.
-    /// The [class][NewExpressionNode::class] identifier is not visited automatically.
     fn visit_new_expr(&mut self, n: &NewExpressionNode, ctx: ExpressionTraversalContext) -> NewExpressionTraversalPolicy { Default::default() }
-    /// Called after visiting an instantiation expression and possibly its [lifetime_obj][NewExpressionNode::lifetime_obj] node.
+    /// Called after visiting an instantiation expression and possibly also children nodes specified in traversal policy.
     fn exit_new_expr(&mut self, n: &NewExpressionNode, ctx: ExpressionTraversalContext) {}
 
     /// Called when visiting a type-casting expression.
-    /// Should return whether to traverse into this node's [value][NewExpressionNode::class] node. True by default.
-    /// The [target_type][NewExpressionNode::target_type] identifier is not visited automatically.
     fn visit_type_cast_expr(&mut self, n: &TypeCastExpressionNode, ctx: ExpressionTraversalContext) -> TypeCastExpressionTraversalPolicy { Default::default() }
-    /// Called after visiting a type-casting expression and possibly also its [value][NewExpressionNode::class] node.
+    /// Called after visiting a type-casting expression and possibly also child node specified in traversal policy.
     fn exit_type_cast_expr(&mut self, n: &TypeCastExpressionNode, ctx: ExpressionTraversalContext) {}
 
     /// Called when visiting an unary operation expression.
-    /// Should return whether to traverse into this node's [right][UnaryOperationExpressionNode::right] node. True by default.
-    /// The [operator][UnaryOperationExpressionNode::op] node is not visited automatically.
     fn visit_unary_op_expr(&mut self, n: &UnaryOperationExpressionNode, ctx: ExpressionTraversalContext) -> UnaryOperationExpressionTraversalPolicy { Default::default() }
-    /// Called after visiting an unary operation expression and possibly also its [right][UnaryOperationExpressionNode::right] node.
+    /// Called after visiting an unary operation expression and possibly also children nodes specified in traversal policy.
     fn exit_unary_op_expr(&mut self, n: &UnaryOperationExpressionNode, ctx: ExpressionTraversalContext) {}
 
     /// Called when visiting a binary operation expression.
-    /// Should return whether to traverse into to this node's [left][BinaryOperationExpressionNode::left] 
-    /// and [right][BinaryOperationExpressionNode::right] nodes. Both true by default.
-    /// The [operator][BinaryOperationExpressionNode::op] node is not visited automatically.
     fn visit_binary_op_expr(&mut self, n: &BinaryOperationExpressionNode, ctx: ExpressionTraversalContext) -> BinaryOperationExpressionTraversalPolicy { Default::default() }
-    /// Called after visiting a binary operation expression and possibly also its [left][BinaryOperationExpressionNode::left] 
-    /// and [right][BinaryOperationExpressionNode::right] nodes.
+    /// Called after visiting a binary operation expression and possibly also children nodes specified in traversal policy.
     fn exit_binary_op_expr(&mut self, n: &BinaryOperationExpressionNode, ctx: ExpressionTraversalContext) {}
 
     /// Called when visiting an assignment operation expression.
-    /// Should return whether to traverse into this node's [left][AssignmentOperationExpressionNode::left] 
-    /// and [right][AssignmentOperationExpressionNode::right] nodes. Both true by default.
-    /// The [operator][AssignmentOperationExpressionNode::op] node is not visited automatically.
     fn visit_assign_op_expr(&mut self, n: &AssignmentOperationExpressionNode, ctx: ExpressionTraversalContext) -> AssignmentOperationExpressionTraversalPolicy { Default::default() }
-    /// Called after visiting an assignment operation expression and possibly also 
-    /// its [left][AssignmentOperationExpressionNode::left] and [right][AssignmentOperationExpressionNode::right] nodes.
+    /// Called after visiting an assignment operation expression and possibly also children nodes specified in traversal policy.
     fn exit_assign_op_expr(&mut self, n: &AssignmentOperationExpressionNode, ctx: ExpressionTraversalContext) {}
 
     /// Called when visiting a ternary conditional expression (expr1 ? expr2 : expr3).
-    /// Should return whether to traverse into this node's [cond][TernaryConditionalExpressionNode::cond], 
-    /// [conseq][TernaryConditionalExpressionNode::conseq] and [alt][TernaryConditionalExpressionNode::alt] nodes.
-    /// All true by default.
     fn visit_ternary_cond_expr(&mut self, n: &TernaryConditionalExpressionNode, ctx: ExpressionTraversalContext) -> TernaryConditionalExpressionTraversalPolicy { Default::default() }
-    /// Called after visiting a ternary conditional expression and possiblt also its 
-    /// [cond][TernaryConditionalExpressionNode::cond], [conseq][TernaryConditionalExpressionNode::conseq] 
-    /// and [alt][TernaryConditionalExpressionNode::alt] nodes.
+    /// Called after visiting a ternary conditional expression and possibly also children nodes specified in traversal policy.
     fn exit_ternary_cond_expr(&mut self, n: &TernaryConditionalExpressionNode, ctx: ExpressionTraversalContext) {}
 }
 
 
 
 /// Handle visitations to declaration nodes. Does not include local var declaration.
-/// Nodes that contain visitable children nodes inside them have a corresponding `exit_` function,
-/// which is run after the node itself and its children are visited.
+/// Visitor functions for nodes that contain visitable children nodes inside them return traversal policy objects that dictate if those children are traversed into.
+/// By default all policy fields have `true` value.
+/// These nodes also have a corresponding `exit_` function for them, which is run after the node itself and (possibly) its children are visited.
 #[allow(unused_variables)]
 pub trait DeclarationVisitor {
     /// Called when visiting the highest node in the hierarchy.
-    /// Should return whether to traverse into the body of the script afterwards. True by default.
     fn visit_root(&mut self, n: &RootNode) -> RootTraversalPolicy { Default::default() }
 
     /// Called when visiting a class declaration.
-    /// Should return whether to traverse into the [definition][ClassDeclarationNode::definition] of the class afterwards. True by default.
     fn visit_class_decl(&mut self, n: &ClassDeclarationNode) -> ClassDeclarationTraversalPolicy { Default::default() }
-    /// Called after visiting a class declaration and possibly its [definition][ClassDeclarationNode::definition].
+    /// Called after visiting a class declaration and possibly also children nodes specified in traversal policy.
     fn exit_class_decl(&mut self, n: &ClassDeclarationNode) {}
 
     /// Called when visiting a state declaration.
-    /// Should return whether to traverse into the [definition][StateDeclarationNode::definition] of the state afterwards. True by default.
     fn visit_state_decl(&mut self, n: &StateDeclarationNode) -> StateDeclarationTraversalPolicy { Default::default() }
-    /// Called after visiting a state declaration and possibly its [definition][StateDeclarationNode::definition].
+    /// Called after visiting a state declaration and possibly also children nodes specified in traversal policy.
     fn exit_state_decl(&mut self, n: &StateDeclarationNode) {}
 
     /// Called when visiting a struct declaration.
-    /// Should return whether to traverse into the [definition][StructDeclarationNode::definition] of the struct afterwards. True by default.
     fn visit_struct_decl(&mut self, n: &StructDeclarationNode) -> StructDeclarationTraversalPolicy { Default::default() }
-    /// Called after visiting a struct declaration and possibly its [definition][StructDeclarationNode::definition].
+    /// Called after visiting a struct declaration and possibly also children nodes specified in traversal policy.
     fn exit_struct_decl(&mut self, n: &StructDeclarationNode) {}
 
     /// Called when visiting an enum declaration.
-    /// Should return whether to traverse into the [definition][EnumDeclarationNode::definition] of the enum afterwards. True by default.
     fn visit_enum_decl(&mut self, n: &EnumDeclarationNode) -> EnumDeclarationTraversalPolicy { Default::default() }
-    /// Called after visiting an enum declaration and possibly its [definition][EnumDeclarationNode::definition].
+    /// Called after visiting an enum declaration and possibly also children nodes specified in traversal policy.
     fn exit_enum_decl(&mut self, n: &EnumDeclarationNode) {}
     /// Called when visiting enum variant's declaration.
     fn visit_enum_variant_decl(&mut self, n: &EnumVariantDeclarationNode) {}
@@ -157,9 +125,8 @@ pub trait DeclarationVisitor {
     fn visit_member_default_val(&mut self, n: &MemberDefaultValueNode, ctx: PropertyTraversalContext) {}
 
     /// Called when visiting a `defaults` block.
-    /// Should return whether to traverse into its [assignment][MemberDefaultsBlockNode::iter] nodes.
     fn visit_member_defaults_block(&mut self, n: &MemberDefaultsBlockNode, ctx: PropertyTraversalContext) -> MemberDefaultsBlockTraversalPolicy { Default::default() }
-    /// Called after visitng a `defaults` block and possibly also its assignment nodes.
+    /// Called after visitng a `defaults` block and possibly also children nodes specified in traversal policy.
     fn exit_member_defaults_block(&mut self, n: &MemberDefaultsBlockNode, ctx: PropertyTraversalContext) {}
 
     /// Called when visiting a default value assignment inside a `defaults` block.
@@ -175,56 +142,49 @@ pub trait DeclarationVisitor {
     fn visit_func_param_group(&mut self, n: &FunctionParameterGroupNode, ctx: FunctionTraversalContext) {}
 
     /// Called when visiting a global function declaration.
-    /// Should return whether to traverse into [parameters][GlobalFunctionDeclarationNode::params] of the function. True by default.
     fn visit_global_func_decl(&mut self, n: &GlobalFunctionDeclarationNode) -> GlobalFunctionDeclarationTraversalPolicy { Default::default() }
-    /// Called after visiting global function declaration and possibly also its [parameters][GlobalFunctionDeclarationNode::params].
+    /// Called after visiting global function declaration and possibly also children nodes specified in traversal policy.
     fn exit_global_func_decl(&mut self, n: &GlobalFunctionDeclarationNode) {}
 
     /// Called when visiting a member function declaration (i.e. a method).
-    /// Should return whether to traverse into [parameters][MemberFunctionDeclarationNode::params] of the function. True by default.
     fn visit_member_func_decl(&mut self, n: &MemberFunctionDeclarationNode, ctx: PropertyTraversalContext) -> MemberFunctionDeclarationTraversalPolicy { Default::default() }
-    /// Called after visiting member function declaration and possibly also its [parameters][MemberFunctionDeclarationNode::params].
+    /// Called after visiting member function declaration and possibly also children nodes specified in traversal policy.
     fn exit_member_func_decl(&mut self, n: &MemberFunctionDeclarationNode, ctx: PropertyTraversalContext) {}
 
     /// Called when visiting an event function declaration.
-    /// Should return whether to traverse into [parameters][EventDeclarationNode::params] of the function. True by default.
     fn visit_event_decl(&mut self, n: &EventDeclarationNode, ctx: PropertyTraversalContext) -> EventDeclarationTraversalPolicy { Default::default() }
-    /// Called after visiting member function declaration and possibly also its [parameters][EventDeclarationNode::params].
+    /// Called after visiting member function declaration and possibly also children nodes specified in traversal policy.
     fn exit_event_decl(&mut self, n: &EventDeclarationNode, ctx: PropertyTraversalContext) {}
 }
 
 
 
 /// Handle visitations to statement nodes.
-/// Nodes that contain visitable children nodes inside them have a corresponding `exit_` function,
-/// which is run after the node itself and its children are visited.
+/// Visitor functions for nodes that contain visitable children nodes inside them return traversal policy objects that dictate if those children are traversed into.
+/// By default all policy fields have `true` value.
+/// These nodes also have a corresponding `exit_` function for them, which is run after the node itself and (possibly) its children are visited.
 #[allow(unused_variables)]
 pub trait StatementVisitor {    
     /// Called when visiting a local variable declaration inside a function.
     fn visit_local_var_decl_stmt(&mut self, n: &VarDeclarationNode, ctx: StatementTraversalContext) {}
 
     /// Called when visiting an expression statement inside a function.
     fn visit_expr_stmt(&mut self, n: &ExpressionStatementNode, ctx: StatementTraversalContext) {}
-
+    
     //TODO! add missing exit_ functions
     /// Called when visiting a `for` loop.
-    /// Should return whether to traverse into the [body][ForLoopNode::body] of the loop. True by default.
     fn visit_for_stmt(&mut self, n: &ForLoopNode, ctx: StatementTraversalContext) -> ForLoopTraversalPolicy { Default::default() }
 
     /// Called when visiting a `while` loop.
-    /// Should return whether to traverse into the [body][WhileLoopNode::body] of the loop. True by default.
     fn visit_while_stmt(&mut self, n: &WhileLoopNode, ctx: StatementTraversalContext) -> WhileLoopTraversalPolicy { Default::default() }
 
     /// Called when visiting a `do-while` loop.
-    /// Should return whether to traverse into the [body][DoWhileLoopNode::body] of the loop. True by default.
     fn visit_do_while_stmt(&mut self, n: &DoWhileLoopNode, ctx: StatementTraversalContext) -> DoWhileLoopTraversalPolicy { Default::default() }
 
     /// Called when visiting an `if` condition.
-    /// Should return whether to traverse into the [body][IfConditionalNode::body] of the statement. True by default.
     fn visit_if_stmt(&mut self, n: &IfConditionalNode, ctx: StatementTraversalContext) -> IfConditionalTraversalPolicy { Default::default() }
 
     /// Called when visiting a `switch` statement.
-    /// Should return whether to traverse into [body][SwitchConditionalNode::body] of the statement. True by default.
     fn visit_switch_stmt(&mut self, n: &SwitchConditionalNode, ctx: StatementTraversalContext) -> SwitchConditionalTraversalPolicy { Default::default() }
 
     /// Called when visiting a `case` label inside a `switch` statement.
@@ -246,7 +206,6 @@ pub trait StatementVisitor {
     fn visit_delete_stmt(&mut self, n: &DeleteStatementNode, ctx: StatementTraversalContext) {}
 
     /// Called when visiting a function block. This may mean a function definition or a scope inside that function.
-    /// Should return whether to traverse into [statements][FunctionBlockNode::iter] of the block. True by default.
     fn visit_block_stmt(&mut self, n: &FunctionBlockNode, ctx: FunctionBlockTraversalContext) -> FunctionBlockTraversalPolicy { Default::default() }
 
     /// Called when visiting a NOP statement.