add some docs

crates/red_knot_python_semantic/src/types.rs

@@ -55,6 +55,9 @@ pub(crate) fn definition_ty<'db>(db: &'db dyn Db, definition: Definition<'db>) -
     inference.definition_ty(definition)
 }
 
+/// Infer the combined type of an array of [`Definition`].
+/// Will return a union if there are more than definition, or at least one plus the possibility of
+/// Unbound.
 pub(crate) fn definitions_ty<'db>(
     db: &'db dyn Db,
     definitions: &[Definition<'db>],

crates/red_knot_python_semantic/src/types/infer.rs

@@ -21,6 +21,7 @@ use crate::semantic_index::semantic_index;
 use crate::semantic_index::symbol::NodeWithScopeKind;
 
 /// Infer all types for a [`Definition`] (including sub-expressions).
+/// Use when resolving a symbol name use or public type of a symbol.
 #[salsa::tracked(return_ref)]
 pub(crate) fn infer_definition_types<'db>(
     db: &'db dyn Db,
@@ -34,6 +35,9 @@ pub(crate) fn infer_definition_types<'db>(
 }
 
 /// Infer all types for an [`Expression`] (including sub-expressions).
+/// Use rarely; only for cases where we'd otherwise risk double-inferring an expression (RHS of an
+/// assignment, which might be unpacking/multi-target and thus part of multiple definitions, or a
+/// type narrowing guard expression (e.g. if statement test node).
 #[allow(unused)]
 #[salsa::tracked(return_ref)]
 pub(crate) fn infer_expression_types<'db>(
@@ -47,7 +51,9 @@ pub(crate) fn infer_expression_types<'db>(
     TypeInferenceBuilder::new(db, InferenceRegion::Expression(expression), index).finish()
 }
 
-/// Infer all types for `scope`.
+/// Infer all types for a [`ScopeId`], including all definitions and expressions.
+/// Use when checking a scope, or needing to provide a type for an arbitrary expression in the
+/// scope.
 #[salsa::tracked(return_ref)]
 pub(crate) fn infer_scope_types<'db>(db: &'db dyn Db, scope: ScopeId<'db>) -> TypeInference<'db> {
     let _span = tracing::trace_span!("infer_scope_types", ?scope).entered();