clarify declarations/locals and unnameable semantics

crates/dash_compiler/src/lib.rs

@@ -348,7 +348,6 @@ impl<'interner> FunctionCompiler<'interner> {
 
     /// This is the same as `find_local` but should be used
     /// when type_infer must have discovered/registered the local variable in the current scope.
-    /// It would be *wrong* to go up scopes sometimes.
     fn find_local_from_binding(&mut self, binding: Binding) -> u16 {
         self.decl_to_slot.slot_from_local(binding.id)
     }

crates/dash_middle/src/compiler/scope.rs

@@ -12,7 +12,10 @@ pub struct LimitExceededError;
 
 #[derive(Debug, Clone)]
 pub struct FunctionScope {
-    // TODO: document the difference between this and `declarations`
+    /// All locals that are declared in this function.
+    /// Every scope that this function encloses (including the function's `Scope` itself) will have its own declarations.
+    /// Some scopes may not have any declarations at all, such as unnameable locals.
+    /// There can also be multiple locals with the same name.
     pub locals: Vec<Local>,
 }
 impl FunctionScope {
@@ -40,6 +43,9 @@ pub struct Scope {
     pub kind: ScopeKind,
     pub parent: Option<ScopeId>,
     pub subscopes: Vec<ScopeId>,
+    /// All variable declarations in this scope.
+    /// It contains the identifier, as well as the local slot
+    /// (index into `functions` of the enclosing function scope).
     pub declarations: Vec<(Symbol, u16)>,
 }
 

crates/dash_middle/src/parser/statement.rs

@@ -685,7 +685,8 @@ pub enum VariableDeclarationKind {
 
     /// Unnameable variables cannot be referred to by JavaScript code directly and are created by the compiler
     ///
-    /// TODO: be more detailed about the semantics here
+    /// Multiple unnamed variables of the same name can exist in a function's `locals` vec and all `find` operations
+    /// on the `ScopeGraph` will never consider unnamed variables.
     #[display(fmt = "__intrinsic_var")]
     Unnameable,
 }