Doc comments

Author: sharkdp

crates/red_knot_python_semantic/src/semantic_index/builder.rs

@@ -546,6 +546,19 @@ impl<'db> SemanticIndexBuilder<'db> {
             .simplify_visibility_constraints(snapshot);
     }
 
+    /// Record a constraint that affects the reachability of the current position in the semantic
+    /// index analysis. For example, if we encounter a `if test:` branch, we immediately record
+    /// a `test` constraint, because if `test` later (during type checking) evaluates to `False`,
+    /// we know that all statements that follow in this path of control flow will be unreachable.
+    fn record_reachability_constraint(
+        &mut self,
+        predicate: Predicate<'db>,
+    ) -> ScopedVisibilityConstraintId {
+        let predicate_id = self.add_predicate(predicate);
+        self.record_reachability_constraint_id(predicate_id)
+    }
+
+    /// Similar to [`record_reachability_constraint`], but takes a [`ScopedPredicateId`].
     fn record_reachability_constraint_id(
         &mut self,
         predicate_id: ScopedPredicateId,
@@ -557,14 +570,7 @@ impl<'db> SemanticIndexBuilder<'db> {
             .record_reachability_constraint(visibility_constraint)
     }
 
-    fn record_reachability_constraint(
-        &mut self,
-        predicate: Predicate<'db>,
-    ) -> ScopedVisibilityConstraintId {
-        let predicate_id = self.add_predicate(predicate);
-        self.record_reachability_constraint_id(predicate_id)
-    }
-
+    /// Record the negation of a given reachability/visibility constraint.
     fn record_negated_reachability_constraint(
         &mut self,
         reachability_constraint: ScopedVisibilityConstraintId,

crates/red_knot_python_semantic/src/semantic_index/use_def.rs

@@ -297,6 +297,7 @@ pub(crate) struct UseDefMap<'db> {
     /// [`SymbolBindings`] reaching a [`ScopedUseId`].
     bindings_by_use: IndexVec<ScopedUseId, SymbolBindings>,
 
+    /// Tracks whether or not a given use of a symbol is reachable from the start of the scope.
     reachability_by_use: IndexVec<ScopedUseId, ScopedVisibilityConstraintId>,
 
     /// If the definition is a binding (only) -- `x = 1` for example -- then we need
@@ -347,6 +348,17 @@ impl<'db> UseDefMap<'db> {
         self.bindings_iterator(&self.bindings_by_use[use_id])
     }
 
+    /// Returns true if a given 'use' of a symbol is reachable from the start of the scope.
+    /// For example, in the following code, use `2` is reachable, but `1` and `3` are not:
+    /// ```py
+    /// def f():
+    ///     x = 1
+    ///     if False:
+    ///         x  # 1
+    ///     x  # 2
+    ///     return
+    ///     x  # 3
+    /// ```
     pub(crate) fn is_symbol_use_reachable(&self, db: &dyn crate::Db, use_id: ScopedUseId) -> bool {
         !self
             .visibility_constraints
@@ -560,17 +572,55 @@ pub(super) struct UseDefMapBuilder<'db> {
     pub(super) visibility_constraints: VisibilityConstraintsBuilder,
 
     /// A constraint which describes the visibility of the unbound/undeclared state, i.e.
-    /// whether or not the start of the scope is visible. This is important for cases like
-    /// `if True: x = 1; use(x)` where we need to hide the implicit "x = unbound" binding
-    /// in the "else" branch.
+    /// whether or not a use of a symbol at the current point in control flow would see
+    /// the fake "x = <unbound>" binding at the start of the scope. This is important for
+    /// cases like the following, where we need to hide the implicit unbound binding in
+    /// the "else" branch:
+    /// ```py
+    /// # x = <unbound>
+    ///
+    /// if True:
+    ///     x = 1
+    ///
+    /// use(x)  # the `x = <unbound>` binding is not visible here
+    /// ```
     pub(super) scope_start_visibility: ScopedVisibilityConstraintId,
 
     /// Live bindings at each so-far-recorded use.
     bindings_by_use: IndexVec<ScopedUseId, SymbolBindings>,
 
-    /// Whether or not the scope start is visible for a given use of a symbol.
+    /// Tracks whether or not the scope start is visible at the current point in control flow.
+    /// This is subtly different from `scope_start_visibility`, as we apply these constraints
+    /// at the beginnging of a branch. Visibility constraints, on the other hand, need to be
+    /// applied at the end of a branch, as we apply them retroactively to all live bindings:
+    /// ```py
+    /// y = 1
+    ///
+    /// if test:
+    ///    # we record a reachability constraint of [test] here,
+    ///    # so that it can affect the use of `x`:
+    ///
+    ///    x  # we store a reachability constraint of [test] for this use of `x`
+    ///
+    ///    y = 2
+    ///    
+    ///    # we record a visibility constraint of [test] here, which retroactively affects
+    ///    # the `y = 1` and the `y = 2` binding.
+    /// else:
+    ///    # we record a reachability constraint of [~test] here.
+    ///
+    ///    pass
+    ///
+    ///    # we record a visibility constraint of [~test] here, which retroactively affects
+    ///    # the `y = 1` binding.
+    ///
+    /// use(y)
+    /// ```
+    /// Depending on the value of `test`, the `y = 1`, `y = 2`, or both bindings may be visible.
+    /// The use of `x` is recorded with a reachability constraint of `[test]`.
     reachability: ScopedVisibilityConstraintId,
 
+    /// Tracks whether or not a given use of a symbol is reachable from the start of the scope.
     reachability_by_use: IndexVec<ScopedUseId, ScopedVisibilityConstraintId>,
 
     /// Live declarations for each so-far-recorded binding.