chore: Add comments

Author: ngeor

rusty_linter/src/core/visitor.rs

@@ -3,16 +3,24 @@ use rusty_parser::*;
 
 use crate::LintErrorPos;
 
+/// The result of a visitor.
 pub type VisitResult = Result<(), LintErrorPos>;
 
+/// A visitor can visit an immutable element by reference.
+/// The visitor can mutate its own state.
 pub trait Visitor<T> {
+    /// Visits the given element.
     fn visit(&mut self, element: &T) -> VisitResult;
 }
 
-pub trait PosVisitor {
-    fn set_pos(&mut self, pos: Position);
+/// Indicates an object that can hold the most recently visited [Position].
+pub trait SetPosition {
+    /// Sets the most recently visited [Position].
+    fn set_position(&mut self, pos: Position);
 }
 
+// Blanket implementation for Vec
+
 impl<P, T> Visitor<Vec<T>> for P
 where
     P: Visitor<T>,
@@ -25,26 +33,35 @@ where
     }
 }
 
+// Blanket implementation for Positioned
+
 impl<P, T> Visitor<Positioned<T>> for P
 where
-    P: Visitor<T> + PosVisitor,
+    P: Visitor<T> + SetPosition,
 {
     fn visit(&mut self, element: &Positioned<T>) -> VisitResult {
         let Positioned { element, pos } = element;
-        self.set_pos(*pos);
+        self.set_position(*pos);
         self.visit(element)
     }
 }
 
+/// Indicates a visitor that can visit global statements
+/// but does not enter the implementations of functions or subs.
+pub trait ShallowGlobalStatementVisitor:
+    Visitor<DefType>
+    + Visitor<FunctionDeclaration>
+    + Visitor<FunctionImplementation>
+    + Visitor<Statement>
+    + Visitor<SubDeclaration>
+    + Visitor<SubImplementation>
+    + Visitor<UserDefinedType>
+{
+}
+
 impl<P> Visitor<GlobalStatement> for P
 where
-    P: Visitor<DefType>
-        + Visitor<FunctionDeclaration>
-        + Visitor<FunctionImplementation>
-        + Visitor<Statement>
-        + Visitor<SubDeclaration>
-        + Visitor<SubImplementation>
-        + Visitor<UserDefinedType>,
+    P: ShallowGlobalStatementVisitor,
 {
     fn visit(&mut self, element: &GlobalStatement) -> VisitResult {
         match element {

rusty_linter/src/pre_linter/main.rs

@@ -1,5 +1,6 @@
 use crate::core::IntoTypeQualifier;
-use crate::core::PosVisitor;
+use crate::core::SetPosition;
+use crate::core::ShallowGlobalStatementVisitor;
 use crate::core::TypeResolverImpl;
 use crate::core::VisitResult;
 use crate::core::Visitor;
@@ -94,8 +95,8 @@ impl MainContext {
     }
 }
 
-impl PosVisitor for MainContext {
-    fn set_pos(&mut self, pos: Position) {
+impl SetPosition for MainContext {
+    fn set_position(&mut self, pos: Position) {
         self.declaration_pos = pos;
     }
 }
@@ -180,3 +181,5 @@ impl Visitor<UserDefinedType> for MainContext {
         )
     }
 }
+
+impl ShallowGlobalStatementVisitor for MainContext {}