From 8e977e0101d388ec863f5f9b07d270b44dc9ef37 Mon Sep 17 00:00:00 2001
From: Aron Zwaan <aronzwaan@gmail.com>
Date: Wed, 6 Dec 2023 14:45:09 +0100
Subject: [PATCH] Document all public API's; finetune API

---
 scopegraphs-lib/src/completeness.rs           |  89 ++++++-
 scopegraphs-lib/src/label.rs                  |   1 +
 scopegraphs-lib/src/lib.rs                    | 230 ++++++++++++------
 scopegraphs-lib/src/resolve/containers/env.rs |  25 +-
 scopegraphs-lib/src/resolve/containers/mod.rs |   4 +
 .../src/resolve/containers/path.rs            |  35 +--
 .../src/resolve/containers/scope.rs           |  18 +-
 .../src/resolve/{topdown.rs => lookup.rs}     | 189 +++++++++-----
 scopegraphs-lib/src/resolve/mod.rs            |  54 ++--
 9 files changed, 440 insertions(+), 205 deletions(-)
 rename scopegraphs-lib/src/resolve/{topdown.rs => lookup.rs} (66%)

diff --git a/scopegraphs-lib/src/completeness.rs b/scopegraphs-lib/src/completeness.rs
index 5c61560..6efc091 100644
--- a/scopegraphs-lib/src/completeness.rs
+++ b/scopegraphs-lib/src/completeness.rs
@@ -1,3 +1,17 @@
+//! This module contains several utilities to guarantee query stability.
+//! Query stability means that the result of a query, once resolved, will remain valid after future
+//! additions to the scope graph.
+//! This allows safe interleaving of name resolution and scope graph construction.
+//!
+//! The main trait of this module is [`Completeness`]. An instance of this trait should be passed
+//! to [`super::ScopeGraph::new`] to obtain a correct scope graph instance.
+//!
+//! Currently the module contains two safe implementations.
+//! [`ImplicitClose`] is the easiest to use, and most likely the preferred choice for simple
+//! sequential type checkers.
+//! [`ExplicitClose`] requires some manual bookkeeping, but allows more flexible handling of
+//! queries. This is the most suitable choice for type checkers that need to do dynamic scheduling.
+
 use std::{collections::HashSet, hash::Hash};
 
 use crate::label::Label;
@@ -12,6 +26,26 @@ use private::Sealed;
 
 /*** Completeness trait ***/
 
+/// Types implementing this trait have the responsibility to guarantee query stability.
+///
+/// This means that the result of a query, once computed, may not be invalidated by later extensions
+/// of the scope graph.
+///
+/// A [`super::ScopeGraph`] will call the handlers of its completeness on each operation.
+/// For scope addition and data access, it can update some internal state.
+/// For edge addition and retrieval, it can override/augment the default result as well.
+///
+/// The way query stability is guaranteed is very flexible. Current implementations use
+/// - critical edges, explicitly closed by the client ([`ExplicitClose`]).
+/// - critical edges, implicitly closed when retrieved ([`ImplicitClose`]).
+///
+/// Future implementations may also:
+/// - delay retrieval of edges until it is closed (by returning a future).
+/// - guarantee stability by retaining residual queries, and checking those do not return any
+///   results for later additions.
+/// - ...
+///
+/// This trait is sealed to ensure only verified implementations are available.
 pub trait Completeness<LABEL, DATA>: Sealed {
     fn cmpl_new_scope(&mut self, inner_scope_graph: &InnerScopeGraph<LABEL, DATA>, scope: Scope);
 
@@ -44,10 +78,25 @@ pub trait Completeness<LABEL, DATA>: Sealed {
 
 /*** Unchecked Completeness Implementation ***/
 
-#[derive(Debug, Default)]
+/// No-Op implementation of [`Completeness`].
+#[derive(Debug)]
 pub struct UncheckedCompleteness {}
 impl Sealed for UncheckedCompleteness {}
 
+impl UncheckedCompleteness {
+    /// Constructs a new instance of [`UncheckedCompleteness`].
+    ///
+    /// # Safety
+    ///
+    /// Marked as `unsafe`, as it does adhere to its contract (guaranteeing stability).
+    ///
+    /// Unless you are sure you really need this, consider alternatives
+    /// such as [`ImplicitClose`] or [`ExplicitClose`].
+    pub unsafe fn new() -> Self {
+        Self {}
+    }
+}
+
 impl<LABEL: Hash + Eq, DATA> Completeness<LABEL, DATA> for UncheckedCompleteness {
     fn cmpl_new_scope(&mut self, _: &InnerScopeGraph<LABEL, DATA>, _: Scope) {}
 
@@ -109,15 +158,23 @@ impl<LABEL: Hash + Eq> CriticalEdgeSet<LABEL> {
 
 pub struct Witness(pub(super) ()); // Prevent abuse of trait function bt requiring argument that can only be constructed locally.
 
+/// Sub-trait of [`Completeness`] that uses _critical edges_ (scope-label pairs) to manage completeness.
+///
+/// Provides utility function to create scopes with particular open edges.
+///
+/// Should not be called externally, but only from utility function on [`super::ScopeGraph`].
 pub trait CriticalEdgeBasedCompleteness<LABEL, DATA>: Completeness<LABEL, DATA> {
     fn init_scope_with(&mut self, open_edges: HashSet<LABEL>, _witness: Witness);
 }
 
+/// Error returned when attempting to add an edge with a label that is already closed in that scope.
 #[derive(Debug)]
-pub enum EdgeClosedError<LABEL> {
-    EdgeClosed { scope: Scope, label: LABEL },
+pub struct EdgeClosedError<LABEL> {
+    pub scope: Scope,
+    pub label: LABEL,
 }
 
+/// Value returned when a query cannot yet be computed because some edge it depends on is still closed.
 #[derive(Debug)]
 pub struct Delay<LABEL> {
     pub scope: Scope,
@@ -128,6 +185,17 @@ pub(crate) type EdgesOrDelay<EDGES, LABEL> = Result<EDGES, Delay<LABEL>>;
 
 /*** Weakly-Critical-Edge Based Completeness Checking with Explicit Closing ***/
 
+/// Critical-edge based [`Completeness`] implementation.
+///
+/// Unlike [`ImplicitClose`], this implementation shifts responsibility of closing edges to the
+/// _type checker writer_. I.e., they have to insert `sg.close(scope, label)` statements at the
+/// appropriate positions in the code.
+///
+/// Returns [`EdgeClosedError`] when an edge is added to a scope in which the label is already
+/// closed (by an explicit close of the type checker writer).
+///
+/// Returns [`Delay`] when edges are retrieved (e.g. during query resolution) for an edge that is
+/// not yet closed.
 pub struct ExplicitClose<LABEL> {
     critical_edges: CriticalEdgeSet<LABEL>,
 }
@@ -172,7 +240,7 @@ impl<LABEL: Hash + Eq + Label, DATA> Completeness<LABEL, DATA> for ExplicitClose
             inner_scope_graph.add_edge(src, lbl, dst);
             Ok(())
         } else {
-            Err(EdgeClosedError::EdgeClosed {
+            Err(EdgeClosedError {
                 scope: src,
                 label: lbl,
             })
@@ -207,13 +275,22 @@ impl<LABEL: Hash + Eq + Label, DATA> CriticalEdgeBasedCompleteness<LABEL, DATA>
 }
 
 impl<LABEL: Hash + Eq> ExplicitClose<LABEL> {
-    pub fn close(&mut self, scope: Scope, label: &LABEL) {
+    pub(super) fn close(&mut self, scope: Scope, label: &LABEL) {
         self.critical_edges.close(scope, label);
     }
 }
 
 /*** Weakly-Critical-Edge Based Completeness Checking with Implicit Closing ***/
 
+/// Critical-edge based [`Completeness`] implementation.
+///
+/// Unlike [`ExplicitClose`], this implementation will implicitly close edges once traversed.
+/// This does not require special attention from the type checker writer.
+///
+/// Returns [`EdgeClosedError`] when an edge is added to a scope in which the label is already
+/// closed (because `get_edges(s, l, ...)` was called earlier.
+///
+/// When edges are retrieved (e.g. during query resolution) the `(src, label)` edge is closed.
 pub struct ImplicitClose<LABEL> {
     critical_edges: CriticalEdgeSet<LABEL>,
 }
@@ -260,7 +337,7 @@ impl<LABEL: Hash + Eq + Label, DATA> Completeness<LABEL, DATA> for ImplicitClose
             Ok(())
         } else {
             // FIXME: provide reason (queries) that made this edge closed?
-            Err(EdgeClosedError::EdgeClosed {
+            Err(EdgeClosedError {
                 scope: src,
                 label: lbl,
             })
diff --git a/scopegraphs-lib/src/label.rs b/scopegraphs-lib/src/label.rs
index 19079ef..4f02136 100644
--- a/scopegraphs-lib/src/label.rs
+++ b/scopegraphs-lib/src/label.rs
@@ -1,3 +1,4 @@
+/// Trait that allows iterating over all labels.
 pub trait Label {
     fn iter() -> impl Iterator<Item = Self>
     where
diff --git a/scopegraphs-lib/src/lib.rs b/scopegraphs-lib/src/lib.rs
index 8ad50e1..97ffc48 100644
--- a/scopegraphs-lib/src/lib.rs
+++ b/scopegraphs-lib/src/lib.rs
@@ -14,6 +14,7 @@ use completeness::{CriticalEdgeBasedCompleteness, ExplicitClose, Witness};
 
 use self::completeness::UncheckedCompleteness;
 
+/// Representation of scopes (nodes in the scope graph).
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct Scope(usize);
 
@@ -26,35 +27,14 @@ impl Debug for Scope {
 // Mutability: RefCell in Scope, not Scope in RefCell
 // Concurrency: RW-lock on edges
 
-/// Scope Graph operations.
-///
-/// This trait describes scope graphs, and the primitive operations that can be applied on them.
-/// As a data structure, scope graphs are simple graphs with labeled nodes and labeled, directed edges.
-///
-/// This trait has three associated types:
-/// - [`InnerScopeGraph::Scope`]: the type of the nodes.
-/// - [`InnerScopeGraph::Label`]: the type of the edge labels.
-/// - [`InnerScopeGraph::Data`]: the type of the scope/node labels.
-///
-/// The data structure has been designed for typical scope graph usage scenario's.
-/// For example, there is no support for _removing_ scopes or edges, as this usually does not happen in scope graphs.
-/// In addition, there is no data type for edges, as edges should only be traversed, but never leak outside the scope graph structure.
-/// Finally, although not made explicit, [`InnerScopeGraph::Label`] should be a finite, iterable set.
-///
-/// Typical scope graph implementations will take ownership of the nodes, but only store references to the data that is associated with them.
-///
-/// Type parameters:
-/// - [`SCOPE`] Type of nodes.
-/// - [`LABEL`] Type of edge labels.
-/// - [`DATA`] Type of data associated with nodes.
 #[derive(Default)]
-pub struct InnerScopeGraph<LABEL, DATA /*, META */> {
+pub struct InnerScopeGraph<LABEL, DATA> {
     edges: Vec<HashMap<LABEL, HashSet<Scope>>>, // FIXME: BTreeMap? Vectors? Whatever?
     data: Vec<DATA>,
 }
 
 impl<LABEL, DATA> InnerScopeGraph<LABEL, DATA> {
-    pub fn new() -> Self {
+    fn new() -> Self {
         Self {
             edges: Vec::new(),
             data: Vec::new(),
@@ -63,19 +43,7 @@ impl<LABEL, DATA> InnerScopeGraph<LABEL, DATA> {
 
     /// Adds a new scope to the graph, with `data` as its associated data.
     /// After this operation, all future calls to [`InnerScopeGraph::get_data`] on this scope will return the associated data.
-    ///
-    /// Example:
-    /// ```ignore
-    /// # use InnerScopeGraphs::InnerScopeGraph::InnerScopeGraph;
-    /// let mut sg : InnerScopeGraph<i32, i32, i32> = InnerScopeGraph::new();
-    /// let data = 42;
-    ///
-    /// let scope = sg.add_scope(&data);
-    ///
-    /// let newData = sg.get_data(scope);
-    /// assert_eq!(data, *newData);
-    /// ```
-    pub fn add_scope(&mut self, data: DATA) -> Scope {
+    fn add_scope(&mut self, data: DATA) -> Scope {
         let id = self.data.len();
         self.data.push(data);
         self.edges.push(HashMap::with_capacity(0));
@@ -91,25 +59,7 @@ impl<LABEL, DATA> InnerScopeGraph<LABEL, DATA> {
 impl<'a, LABEL: Hash + Eq, DATA> InnerScopeGraph<LABEL, DATA> {
     /// Adds a new edge from `src`, to `dst`, with label `lbl` to the scope graph.
     /// After this operation, all future calls to [`InnerScopeGraph::get_edges`] on the source will contain the destination.
-    ///
-    /// Example:
-    /// ```ignore
-    /// # use InnerScopeGraphs::{InnerScopeGraph::InnerScopeGraph, Label};
-    ///
-    /// #[derive(Label, Eq, PartialEq, Copy, Clone)]
-    /// enum Label { LEX }
-    /// let mut sg : InnerScopeGraph<i32, Label, i32> = InnerScopeGraph::new();
-    /// let data = 42;
-    ///
-    /// let src = sg.add_scope(&data);
-    /// let dst = sg.add_scope(&data);
-    /// sg.add_edge(src, &Label::LEX, dst);
-    ///
-    /// let mut  dst_iter = sg.get_edges(src, &Label::LEX);
-    /// assert!(dst_iter.any(|d| d == *dst));
-    /// ```
-    ///
-    pub fn add_edge(&mut self, src: Scope, lbl: LABEL, dst: Scope) {
+    fn add_edge(&mut self, src: Scope, lbl: LABEL, dst: Scope) {
         self.edges[src.0].entry(lbl).or_default().insert(dst);
     }
 
@@ -124,6 +74,19 @@ impl<'a, LABEL: Hash + Eq, DATA> InnerScopeGraph<LABEL, DATA> {
     }
 }
 
+/// Scope Graph data structure.
+///
+/// As a data structure, scope graphs are simple graphs with labeled nodes and labeled, directed edges.
+///
+/// This trait has three type parameters:
+/// - [`LABEL`]: the type of the edge labels.
+/// - [`DATA`]: the type of the scope/node labels.
+/// - [`CMPL`]: metadata that guarantees query stability (i.e., query results remain valid in the future).
+///
+/// The data structure has been designed for typical scope graph usage scenario's.
+/// For example, there is no support for _removing_ scopes or edges, as this usually does not happen in scope graphs.
+/// In addition, there is no data type for edges, as edges should only be traversed, but never leak outside the scope graph structure.
+/// Finally, although not made explicit, [`LABEL`] should be a finite, iterable set.
 pub struct ScopeGraph<LABEL, DATA, CMPL> {
     inner_scope_graph: InnerScopeGraph<LABEL, DATA>,
     completeness: RefCell<CMPL>,
@@ -138,8 +101,13 @@ impl<LABEL, DATA, CMPL> ScopeGraph<LABEL, DATA, CMPL> {
     }
 }
 impl<LABEL, DATA> ScopeGraph<LABEL, DATA, UncheckedCompleteness> {
-    pub fn raw() -> Self {
-        Self::new(UncheckedCompleteness::default())
+    /// Creates a new scope graph with [`UncheckedCompleteness`] as its completeness validation.
+    ///
+    /// # Safety
+    ///
+    /// Unsafe, because [`UncheckedCompleteness`] does not actually guarantee query stability.
+    pub unsafe fn raw() -> Self {
+        Self::new(UncheckedCompleteness::new())
     }
 }
 
@@ -147,7 +115,8 @@ impl<LABEL, DATA, CMPL> ScopeGraph<LABEL, DATA, CMPL>
 where
     CMPL: Completeness<LABEL, DATA>,
 {
-    pub fn new_scope(&mut self, data: DATA) -> Scope {
+    /// Add a new scope to the scope graph, with `data` as its label.
+    pub fn add_scope(&mut self, data: DATA) -> Scope {
         let scope = self.inner_scope_graph.add_scope(data);
         self.completeness
             .borrow_mut()
@@ -155,29 +124,57 @@ where
         scope
     }
 
-    pub fn new_edge(&mut self, src: Scope, lbl: LABEL, dst: Scope) -> CMPL::NewEdgeResult {
+    /// Add a new edge in the scope graph.
+    ///
+    /// Permission for this is checked by `CMPL`.
+    pub fn add_edge(&mut self, src: Scope, lbl: LABEL, dst: Scope) -> CMPL::NewEdgeResult {
         self.completeness
             .borrow_mut()
             .cmpl_new_edge(&mut self.inner_scope_graph, src, lbl, dst)
     }
 
+    /// Get the data associated with a scope.
     pub fn get_data(&self, scope: Scope) -> &DATA {
         self.inner_scope_graph.get_data(scope)
     }
 
+    /// Get the targets of the outgoing edges of a scope with some label.
+    ///
+    /// Permission for this operation is checked by `CMPL`.
     pub fn get_edges(&self, src: Scope, lbl: LABEL) -> CMPL::GetEdgesResult {
         self.completeness
             .borrow_mut()
             .cmpl_get_edges(&self.inner_scope_graph, src, lbl)
     }
 
-    pub fn new_decl(&mut self, src: Scope, lbl: LABEL, data: DATA) -> CMPL::NewEdgeResult {
+    /// Utility function to add declarations (i.e., scopes with data, without any outgoing edges).
+    ///
+    /// It performs (roughly) the following operation:
+    ///
+    /// ```ignore
+    /// fn add_decl(&mut self, src: Scope, lbl: LABEL, data: DATA) -> CMPL::NewEdgeResult {
+    ///     let s_data = self.add_scope(data);
+    ///     self.add_edge(src, lbl, s_data);
+    /// }
+    /// ```
+    pub fn add_decl(&mut self, src: Scope, lbl: LABEL, data: DATA) -> CMPL::NewEdgeResult {
         // Create scope with no open edges.
         let s_data = self.inner_scope_graph.add_scope(data);
         self.completeness
             .borrow_mut()
             .cmpl_new_complete_scope(&self.inner_scope_graph, s_data);
-        self.new_edge(src, lbl, s_data)
+        self.add_edge(src, lbl, s_data)
+    }
+}
+
+impl<LABEL, DATA, CMPL> ScopeGraph<LABEL, DATA, CMPL>
+where
+    DATA: Default,
+    CMPL: Completeness<LABEL, DATA>,
+{
+    /// Add a new scope to the scope graph, with default data.
+    pub fn add_scope_default(&mut self) -> Scope {
+        self.add_scope(DATA::default())
     }
 }
 
@@ -185,7 +182,8 @@ impl<LABEL: Hash + Eq, DATA, CMPL> ScopeGraph<LABEL, DATA, CMPL>
 where
     CMPL: CriticalEdgeBasedCompleteness<LABEL, DATA>,
 {
-    pub fn new_scope_with<I>(&mut self, data: DATA, open_edges: I) -> Scope
+    /// Adds a new scope with some open edges.
+    pub fn add_scope_with<I>(&mut self, data: DATA, open_edges: I) -> Scope
     where
         I: IntoIterator<Item = LABEL>,
     {
@@ -195,9 +193,87 @@ where
             .init_scope_with(HashSet::from_iter(open_edges.into_iter()), Witness(()));
         scope
     }
+
+    /// Adds a new scope with no open edges.
+    pub fn add_scope_closed<I>(&mut self, data: DATA) -> Scope
+    where
+        I: IntoIterator<Item = LABEL>,
+    {
+        let scope = self.inner_scope_graph.add_scope(data);
+        self.completeness
+            .borrow_mut()
+            .init_scope_with(HashSet::new(), Witness(()));
+        scope
+    }
+}
+
+impl<LABEL: Hash + Eq, DATA, CMPL> ScopeGraph<LABEL, DATA, CMPL>
+where
+    DATA: Default,
+    CMPL: CriticalEdgeBasedCompleteness<LABEL, DATA>,
+{
+    /// Adds a new scope with some open edges and default data.
+    pub fn add_scope_default_with<I>(&mut self, open_edges: I) -> Scope
+    where
+        I: IntoIterator<Item = LABEL>,
+    {
+        self.add_scope_with(DATA::default(), open_edges)
+    }
+
+    /// Adds a new scope with no open edges and default data.
+    pub fn add_scope_default_closed(&mut self) -> Scope {
+        self.add_scope_with(DATA::default(), HashSet::new())
+    }
 }
 
 impl<LABEL: Hash + Eq, DATA> ScopeGraph<LABEL, DATA, ExplicitClose<LABEL>> {
+    /// Closes an edge, (i.e., prohibit future new
+    ///
+    /// For example, the following program will return an error.
+    /// ```
+    /// # use scopegraphs_lib::completeness::ExplicitClose;
+    /// # use scopegraphs_lib::ScopeGraph;
+    /// # use scopegraphs_macros::Label;
+    /// # #[derive(Eq, Hash, PartialEq, Label)] enum Lbl { Def }
+    /// # use Lbl::*;
+    /// let mut sg = ScopeGraph::<Lbl, usize, _>::new(ExplicitClose::default());
+    ///
+    /// let s1 = sg.add_scope_with(0, [Def]);
+    /// let s2 = sg.add_scope_with::<[Lbl; 0]>(42, []);
+    ///
+    /// sg.close(s1, &Def);
+    /// sg.add_edge(s1, Def, s2).expect_err("cannot add edge after closing edge");
+    /// ```
+    ///
+    /// Closing is required to permit queries to traverse these edges:
+    /// ```
+    ///
+    /// # use scopegraphs_lib::completeness::ExplicitClose;
+    /// # use scopegraphs_lib::ScopeGraph;
+    /// # use scopegraphs_macros::{compile_regex, Label};
+    /// # #[derive(Eq, Hash, PartialEq, Label, Debug, Copy, Clone)] enum Lbl { Def }
+    /// # use Lbl::*;
+    /// # compile_regex!(type Regex<Lbl> = Def);
+    /// # use scopegraphs_lib::resolve::lookup::resolve;
+    /// let mut sg = ScopeGraph::<Lbl, usize, _>::new(ExplicitClose::default());
+    ///
+    /// let s1 = sg.add_scope_with(0, [Def]);
+    /// let s2 = sg.add_scope_with::<[Lbl; 0]>(42, []);
+    ///
+    /// // Note: not calling `sg.close(s1, &Def)`
+    ///
+    /// let query_result = resolve(
+    ///     &sg,
+    ///     /* ... */
+    /// #    &Regex::new(),
+    /// #    &|x| *x == 42,
+    /// #    &|_, _,| false,
+    /// #    &|_, _| true,
+    ///     s1
+    /// );
+    ///
+    /// query_result.expect_err("require s1/Def to be closed");
+    /// ```
     pub fn close(&self, scope: Scope, label: &LABEL) {
         self.completeness.borrow_mut().close(scope, label)
     }
@@ -209,17 +285,17 @@ mod test {
 
     #[test]
     fn test_create_scope() {
-        let mut sg: ScopeGraph<usize, usize, _> = ScopeGraph::raw();
-        let scope = sg.new_scope(42);
+        let mut sg: ScopeGraph<usize, usize, _> = unsafe { ScopeGraph::raw() };
+        let scope = sg.add_scope(42);
         assert_eq!(42, *sg.get_data(scope));
     }
 
     #[test]
     fn test_create_two_scopes() {
-        let mut sg: ScopeGraph<usize, usize, _> = ScopeGraph::raw();
+        let mut sg: ScopeGraph<usize, usize, _> = unsafe { ScopeGraph::raw() };
 
-        let s1 = sg.new_scope(1);
-        let s2 = sg.new_scope(2);
+        let s1 = sg.add_scope(1);
+        let s2 = sg.add_scope(2);
 
         assert_eq!(1, *sg.get_data(s1));
         assert_eq!(2, *sg.get_data(s2));
@@ -227,12 +303,12 @@ mod test {
 
     #[test]
     fn test_create_edge() {
-        let mut sg: ScopeGraph<usize, usize, _> = ScopeGraph::raw();
+        let mut sg: ScopeGraph<usize, usize, _> = unsafe { ScopeGraph::raw() };
 
-        let s1 = sg.new_scope(1);
-        let s2 = sg.new_scope(2);
+        let s1 = sg.add_scope(1);
+        let s2 = sg.add_scope(2);
 
-        sg.new_edge(s1, 1, s2);
+        sg.add_edge(s1, 1, s2);
 
         assert_eq!(vec![s2], sg.get_edges(s1, 1));
         assert_eq!(Vec::<Scope>::new(), sg.get_edges(s1, 2));
@@ -240,14 +316,14 @@ mod test {
 
     #[test]
     fn test_create_edges() {
-        let mut sg: ScopeGraph<usize, usize, _> = ScopeGraph::raw();
+        let mut sg: ScopeGraph<usize, usize, _> = unsafe { ScopeGraph::raw() };
 
-        let s1 = sg.new_scope(1);
-        let s2 = sg.new_scope(2);
-        let s3 = sg.new_scope(3);
+        let s1 = sg.add_scope(1);
+        let s2 = sg.add_scope(2);
+        let s3 = sg.add_scope(3);
 
-        sg.new_edge(s1, 1, s2);
-        sg.new_edge(s1, 1, s3);
+        sg.add_edge(s1, 1, s2);
+        sg.add_edge(s1, 1, s3);
 
         assert!(sg.get_edges(s1, 1).contains(&s2));
         assert!(sg.get_edges(s1, 1).contains(&s3));
diff --git a/scopegraphs-lib/src/resolve/containers/env.rs b/scopegraphs-lib/src/resolve/containers/env.rs
index 5061e9e..1ede817 100644
--- a/scopegraphs-lib/src/resolve/containers/env.rs
+++ b/scopegraphs-lib/src/resolve/containers/env.rs
@@ -1,16 +1,25 @@
-use crate::resolve::{DataOrder, Env, ResolvedPath};
+use crate::resolve::{DataEquiv, Env, ResolvedPath};
 use std::fmt::Debug;
 use std::hash::Hash;
 
+/// Interface for environment containers that support the operations required for query resolution.
 pub trait EnvContainer<'sg, LABEL: 'sg, DATA: 'sg>: From<Env<'sg, LABEL, DATA>> {
+    /// Creates a new, container with an empty environment.
     fn empty() -> Self;
 
+    /// Lifts a merge operation into this container.
+    ///
+    /// The resulting container should contain all paths in `self` and all paths in `other`.
     // has functional interface (-> Self) to accommodate Result/Option implementations.
     // e.g., `&mut self` cannot be changed from `Ok(_)` to `Err(_)`
     // implementations that use the interior mutability should return `self`
     fn lift_merge(self, other: Self) -> Self;
 
-    fn lift_shadow<DO: DataOrder<DATA>>(self, sub_env: Self, data_order: DO) -> Self;
+    /// Lifts a shadowing operation into this container.
+    ///
+    /// The resulting container should contain all paths in `self` and all paths in `sub_env`
+    /// that are not shadowed by some path in `self` according to the data order.
+    fn lift_shadow<DO: DataEquiv<DATA>>(self, sub_env: Self, data_equiv: DO) -> Self;
 }
 
 impl<'sg, LABEL, DATA: Debug> EnvContainer<'sg, LABEL, DATA> for Env<'sg, LABEL, DATA>
@@ -28,11 +37,11 @@ where
         self
     }
 
-    fn lift_shadow<DO: DataOrder<DATA>>(mut self, sub_env: Self, data_order: DO) -> Self {
+    fn lift_shadow<DO: DataEquiv<DATA>>(mut self, sub_env: Self, data_equiv: DO) -> Self {
         let filtered_env = sub_env
             .into_iter()
             .filter(|p1| {
-                if let Some(p2) = self.iter().find(|p2| data_order(p1.data, p2.data)) {
+                if let Some(p2) = self.iter().find(|p2| data_equiv(p1.data, p2.data)) {
                     log::info!(
                         "Discarding {:?} in {:?}; shadowed by {:?} in {:?}",
                         p1.data,
@@ -69,10 +78,14 @@ impl<'sg, LABEL: 'sg, DATA: 'sg, EC: EnvContainer<'sg, LABEL, DATA>, E>
     }
 
     fn lift_merge(self, other: Self) -> Self {
+        // Lift the merge if both results are ok.
+        // Otherwise, retain the leftmost error value.
         self.and_then(|ec1| other.map(|ec2| ec1.lift_merge(ec2)))
     }
 
-    fn lift_shadow<DO: DataOrder<DATA>>(self, sub_env: Self, data_order: DO) -> Self {
-        self.and_then(|ec1| sub_env.map(|ec2| ec1.lift_shadow(ec2, data_order)))
+    fn lift_shadow<DO: DataEquiv<DATA>>(self, sub_env: Self, data_equiv: DO) -> Self {
+        // Lift the shadow operations if both results are ok.
+        // Otherwise, retain the leftmost error value.
+        self.and_then(|ec1| sub_env.map(|ec2| ec1.lift_shadow(ec2, data_equiv)))
     }
 }
diff --git a/scopegraphs-lib/src/resolve/containers/mod.rs b/scopegraphs-lib/src/resolve/containers/mod.rs
index f2b43e1..a8a8c74 100644
--- a/scopegraphs-lib/src/resolve/containers/mod.rs
+++ b/scopegraphs-lib/src/resolve/containers/mod.rs
@@ -1,3 +1,7 @@
+//! This module contains some generic containers for data used by the resolution algorithm.
+//! Using these interfaces, the resolution algorithms can deal with custom behavior introduced
+//! by [`super::super::completeness::Completeness`] implementations.
+
 mod scope;
 pub use scope::*;
 
diff --git a/scopegraphs-lib/src/resolve/containers/path.rs b/scopegraphs-lib/src/resolve/containers/path.rs
index cafbca2..50d8a48 100644
--- a/scopegraphs-lib/src/resolve/containers/path.rs
+++ b/scopegraphs-lib/src/resolve/containers/path.rs
@@ -1,7 +1,9 @@
 use crate::resolve::{Env, Path, ResolvedPath};
 use std::hash::Hash;
 
+/// Interface for path containers that support the operations required for query resolution.
 pub trait PathContainer<LABEL, DATA> {
+    /// Type returned by resolving a path to its sub-environment.
     type EnvContainer<'sg>
     where
         DATA: 'sg,
@@ -15,30 +17,10 @@ pub trait PathContainer<LABEL, DATA> {
     ) -> Self::EnvContainer<'sg>;
 }
 
-pub fn flat_map_iterator<
-    'sg,
-    LABEL: 'sg,
-    DATA: 'sg,
-    F: FnMut(Path<LABEL>) -> Env<'sg, LABEL, DATA>,
->(
-    iter: impl Iterator<Item = Path<LABEL>>,
-    f: F,
-) -> Env<'sg, LABEL, DATA>
-where
-    LABEL: Clone + Hash + Eq,
-    for<'a> ResolvedPath<'a, LABEL, DATA>: Hash + Eq,
-{
-    let mut env = Env::new();
-    for sub_env in iter.map(f) {
-        env.merge(sub_env)
-    }
-    env
-}
-
 impl<LABEL, DATA> PathContainer<LABEL, DATA> for Vec<Path<LABEL>>
 where
     LABEL: Clone + Hash + Eq,
-    for<'a> ResolvedPath<'a, LABEL, DATA>: Hash + Eq,
+    DATA: Hash + Eq,
 {
     type EnvContainer<'sg> = Env<'sg, LABEL, DATA> where LABEL: 'sg, DATA: 'sg;
 
@@ -46,7 +28,7 @@ where
         self,
         f: F,
     ) -> Self::EnvContainer<'sg> {
-        flat_map_iterator(self.into_iter(), f)
+        self.into_iter().map(f).collect()
     }
 }
 
@@ -64,12 +46,11 @@ where
         self,
         f: F,
     ) -> Self::EnvContainer<'sg> {
-        match self {
-            Ok(paths) => paths
+        self.and_then(|paths| {
+            paths
                 .into_iter()
                 .map(f)
-                .collect::<Result<Env<'sg, LABEL, DATA>, E>>(),
-            Err(err) => Err(err),
-        }
+                .collect::<Result<Env<'sg, LABEL, DATA>, E>>()
+        })
     }
 }
diff --git a/scopegraphs-lib/src/resolve/containers/scope.rs b/scopegraphs-lib/src/resolve/containers/scope.rs
index 969cf71..a2c693a 100644
--- a/scopegraphs-lib/src/resolve/containers/scope.rs
+++ b/scopegraphs-lib/src/resolve/containers/scope.rs
@@ -1,24 +1,24 @@
 use crate::{resolve::Path, Scope};
 
+/// Interface for scope containers that support the operations required for query resolution.
 pub trait ScopeContainer<LABEL> {
+    /// The type containing paths obtained after stepping to this scope.
     type PathContainer;
 
+    /// Lift the [`Path::step`] operation into this container.
+    ///
+    /// Should retain the contract that for all scopes `s` in `self`, `prefix.step(lbl, s)` is
+    /// included in the resulting path container (excpet cyclic paths).
     fn lift_step(self, lbl: LABEL, prefix: &Path<LABEL>) -> Self::PathContainer;
 }
 
-pub fn lift_step_iterator<'a, LABEL: Copy>(
-    iter: impl Iterator<Item = Scope> + 'a,
-    lbl: LABEL,
-    prefix: &'a Path<LABEL>,
-) -> impl Iterator<Item = Path<LABEL>> + 'a {
-    iter.filter_map(move |s| prefix.step(lbl, s))
-}
-
 impl<LABEL: Copy> ScopeContainer<LABEL> for Vec<Scope> {
     type PathContainer = Vec<Path<LABEL>>;
 
     fn lift_step(self, lbl: LABEL, prefix: &Path<LABEL>) -> Self::PathContainer {
-        lift_step_iterator(self.into_iter(), lbl, prefix).collect()
+        self.into_iter()
+            .filter_map(move |s| prefix.step(lbl, s))
+            .collect()
     }
 }
 
diff --git a/scopegraphs-lib/src/resolve/topdown.rs b/scopegraphs-lib/src/resolve/lookup.rs
similarity index 66%
rename from scopegraphs-lib/src/resolve/topdown.rs
rename to scopegraphs-lib/src/resolve/lookup.rs
index 27b5b30..9807ef5 100644
--- a/scopegraphs-lib/src/resolve/topdown.rs
+++ b/scopegraphs-lib/src/resolve/lookup.rs
@@ -1,3 +1,9 @@
+//! This module contains the lookup-based name resolution algorithm.
+//!
+//! Starting from a reference in a scope, it will traverse the scope graph to find matching declarations.
+//! The versatile set of parameters guides the search to ensure the resulting environment matches
+//! the intended semantics of the reference.
+
 use std::fmt::Debug;
 use std::hash::Hash;
 use std::iter;
@@ -6,19 +12,39 @@ use crate::{
     label::Label,
     resolve::{
         containers::{EnvContainer, PathContainer, ScopeContainer},
-        DataOrder, DataWellformedness, EdgeOrData, Env, LabelOrder, Path, ResolvedPath,
+        DataEquiv, DataWellformedness, EdgeOrData, Env, LabelOrder, Path, ResolvedPath,
     },
     ScopeGraph,
     {completeness::Completeness, Scope},
 };
 use scopegraphs_regular_expressions::RegexMatcher;
 
+/// Entry point of the query resolution. Performs a traversal of the scope graph that results in
+/// an environment containing all declarations matching a reference.
+///
+/// Type parameters:
+/// - `LABEL`: labels in the scope graph.
+/// - `DATA`: Data in the scope graph.
+/// - `CMPL`: the completeness approach (determined by the scope graph). Should be an instance of
+///     [`Completeness`]. This guarantees that the query resolution result will remain valid, even
+///     in the presence of future additions to the scope graph.
+/// - `ENVC`: The [`EnvContainer`] (determined by `CMPL`) used to process environments throughout
+///     the resolution process.
+///
+/// Parameters:
+/// - `sg`: the scope graph in which to perform name resolution.
+/// - `path_wellformedness`: regular expression matcher that indicates which paths are valid.
+///     The labels of all paths in the environment will match the regular expression that this
+///     matcher is derived from.
+/// - `data_wellformedness`: Unary predicate over data that selects valid declarations.
+/// - `label_order`: Label order: the order on labels that indicates which declarations are preferred over others.
+/// - `data_equiv`: Equivalence relation on data that determines which declarations can shadow each other.
 pub fn resolve<'sg: 'query, 'query, LABEL, DATA, CMPL, ENVC>(
     sg: &'sg ScopeGraph<LABEL, DATA, CMPL>,
     path_wellformedness: &'query impl for<'a> RegexMatcher<&'a LABEL>,
     data_wellformedness: &'query impl DataWellformedness<DATA>,
     label_order: &'query impl LabelOrder<LABEL>,
-    data_order: &'query impl DataOrder<DATA>,
+    data_equiv: &'query impl DataEquiv<DATA>,
     source: Scope,
 ) -> ENVC
 where
@@ -42,22 +68,22 @@ where
         sg,
         data_wellformedness,
         label_order,
-        data_order,
+        data_equiv,
     };
 
     context.resolve_all(path_wellformedness, &Path::new(source))
 }
 
-struct ResolutionContext<'sg: 'query, 'query, LABEL, DATA, CMPL, DWF, LO, DO> {
+struct ResolutionContext<'sg: 'query, 'query, LABEL, DATA, CMPL, DWF, LO, DEq> {
     all_edges: Vec<EdgeOrData<LABEL>>,
     sg: &'sg ScopeGraph<LABEL, DATA, CMPL>,
     data_wellformedness: &'query DWF,
     label_order: &'query LO,
-    data_order: &'query DO,
+    data_equiv: &'query DEq,
 }
 
-impl<'sg, 'query, LABEL, DATA, CMPL, DWF, LO, DO, ENVC>
-    ResolutionContext<'sg, 'query, LABEL, DATA, CMPL, DWF, LO, DO>
+impl<'sg, 'query, LABEL, DATA, CMPL, DWF, LO, DEq, ENVC>
+    ResolutionContext<'sg, 'query, LABEL, DATA, CMPL, DWF, LO, DEq>
 where
     LABEL: Copy + Debug,
     DATA: Debug,
@@ -67,11 +93,15 @@ where
     <CMPL::GetEdgesResult as ScopeContainer<LABEL>>::PathContainer:
         PathContainer<LABEL, DATA, EnvContainer<'sg> = ENVC>,
     ENVC: EnvContainer<'sg, LABEL, DATA> + Debug,
-    DO: DataOrder<DATA>,
+    DEq: DataEquiv<DATA>,
     DWF: DataWellformedness<DATA>,
     LO: LabelOrder<LABEL>,
     Path<LABEL>: Clone,
 {
+    /// Finds all paths of which:
+    /// - `path` is a prefix
+    /// - the extension matches `path_wellformedness`
+    /// - the other conditions in `self` are obeyed.
     fn resolve_all(
         &self,
         path_wellformedness: &impl for<'a> RegexMatcher<&'a LABEL>,
@@ -82,7 +112,9 @@ where
             .iter()
             .copied()
             .filter(|e| match *e {
+                // match current scope only if the regular expression is accepting
                 EdgeOrData::Data => path_wellformedness.is_accepting(),
+                // traverse `label` if the `path_wellformedness` accepts words that start with it.
                 EdgeOrData::Edge(label) => path_wellformedness.accepts_prefix([&label]),
             })
             .collect();
@@ -91,6 +123,7 @@ where
         self.resolve_edges(path_wellformedness, &edges, path)
     }
 
+    /// Computes a sub environment for `edges`, for which shadowing is internally applied.
     fn resolve_edges(
         &self,
         path_wellformedness: &impl for<'a> RegexMatcher<&'a LABEL>,
@@ -98,11 +131,13 @@ where
         path: &Path<LABEL>,
     ) -> ENVC {
         let tgt = path.target();
+        // set of labels that are to be resolved last
         let max = self.max(edges);
         let mut env = ENVC::empty();
 
         log::info!("Resolving max-edges {:?} in {:?}", max, tgt);
         for edge in max {
+            // sub-environment that has higher priority that the `max`-environment
             let smaller = self.smaller(edge, edges);
             log::info!(
                 "Resolving(shadowed) {:?} < {:?} in {:?}",
@@ -110,6 +145,7 @@ where
                 edge,
                 tgt
             );
+            //
             env = env.lift_merge(self.resolve_shadow(path_wellformedness, edge, &smaller, path))
         }
 
@@ -117,6 +153,11 @@ where
         env
     }
 
+    /// Computes shadowed environment with following steps:
+    /// - Compute the environment for `edges` (the _base environment_)
+    /// - Compute the environment for `edge` (the _sub-environment_).
+    /// - Insert the paths in the sub-environment in the base environment
+    ///   iff it is not shadowed by some path in the base environment.
     fn resolve_shadow(
         &self,
         path_wellformedness: &impl for<'a> RegexMatcher<&'a LABEL>,
@@ -124,11 +165,14 @@ where
         edges: &[EdgeOrData<LABEL>],
         path: &Path<LABEL>,
     ) -> ENVC {
-        let env: ENVC = self.resolve_edges(path_wellformedness, edges, path);
+        // base environment
+        let base_env: ENVC = self.resolve_edges(path_wellformedness, edges, path);
+        // environment of current (max) label, which might be shadowed by the base environment
         let sub_env = self.resolve_edge(path_wellformedness, edge, path);
-        env.lift_shadow(sub_env, self.data_order)
+        base_env.lift_shadow(sub_env, self.data_equiv)
     }
 
+    /// Compute environment for single edge
     fn resolve_edge(
         &self,
         path_wellformedness: &impl for<'a> RegexMatcher<&'a LABEL>,
@@ -145,6 +189,10 @@ where
         }
     }
 
+    /// Compute environment for single label.
+    ///
+    /// Traverses all outgoing edges from `path.target()` with label `label`,
+    /// and recursively queries from there.
     fn resolve_label(
         &self,
         path_wellformedness: &impl for<'a> RegexMatcher<&'a LABEL>,
@@ -158,6 +206,7 @@ where
         env
     }
 
+    /// Creates single-path environment if the data `path.target()` is matching, or an empty environment otherwise.
     fn resolve_data(&self, path: &Path<LABEL>) -> ENVC {
         let data = self.sg.get_data(path.target());
         if (self.data_wellformedness)(data) {
@@ -169,6 +218,7 @@ where
         }
     }
 
+    /// Computes the edges in `edges` for which no 'greater' edge exists.
     fn max(&self, edges: &[EdgeOrData<LABEL>]) -> Vec<EdgeOrData<LABEL>> {
         let max = edges
             .iter()
@@ -180,6 +230,7 @@ where
         max
     }
 
+    /// Returns all edges in `edges` that are smaller than `edge`.
     fn smaller(
         &self,
         edge: EdgeOrData<LABEL>,
@@ -202,7 +253,7 @@ mod tests {
 
     use scopegraphs::{
         completeness::{Completeness, ExplicitClose, ImplicitClose, UncheckedCompleteness},
-        resolve::{topdown::resolve, EdgeOrData, ResolvedPath},
+        resolve::{lookup::resolve, EdgeOrData, ResolvedPath},
         Scope, ScopeGraph,
     };
 
@@ -214,10 +265,14 @@ mod tests {
     }
     use Lbl::*;
 
-    #[derive(Hash, PartialEq, Eq, Debug)]
+    #[derive(Hash, PartialEq, Eq, Debug, Default)]
     enum TData<'a, T> {
+        #[default]
         NoData,
-        Data { name: &'a str, data: T },
+        Data {
+            name: &'a str,
+            data: T,
+        },
     }
     use TData::*;
 
@@ -245,10 +300,11 @@ mod tests {
 
     #[test]
     fn test_match_data() {
-        let mut scope_graph: ScopeGraph<Lbl, TData<()>, UncheckedCompleteness> = ScopeGraph::raw();
+        let mut scope_graph: ScopeGraph<Lbl, TData<()>, UncheckedCompleteness> =
+            unsafe { ScopeGraph::raw() };
 
-        let s0 = scope_graph.new_scope(NoData);
-        scope_graph.new_decl(s0, Def, TData::from_default("x"));
+        let s0 = scope_graph.add_scope_default();
+        scope_graph.add_decl(s0, Def, TData::from_default("x"));
 
         compile_regex!(type Machine<Lbl> = Def);
 
@@ -270,10 +326,11 @@ mod tests {
 
     #[test]
     fn test_no_match_other_data() {
-        let mut scope_graph: ScopeGraph<Lbl, TData<()>, UncheckedCompleteness> = ScopeGraph::raw();
+        let mut scope_graph: ScopeGraph<Lbl, TData<()>, UncheckedCompleteness> =
+            unsafe { ScopeGraph::raw() };
 
-        let s0 = scope_graph.new_scope(NoData);
-        scope_graph.new_decl(s0, Def, TData::from_default("x"));
+        let s0 = scope_graph.add_scope_default();
+        scope_graph.add_decl(s0, Def, TData::from_default("x"));
 
         compile_regex!(type Machine<Lbl> = Def);
 
@@ -293,13 +350,13 @@ mod tests {
     #[test]
     fn test_regex_enforces_step() {
         let mut scope_graph: ScopeGraph<Lbl, TData<usize>, UncheckedCompleteness> =
-            ScopeGraph::raw();
+            unsafe { ScopeGraph::raw() };
 
-        let s0 = scope_graph.new_scope(NoData);
-        let s1 = scope_graph.new_scope(NoData);
-        scope_graph.new_edge(s0, Lex, s1);
-        scope_graph.new_decl(s0, Def, Data { name: "x", data: 0 });
-        scope_graph.new_decl(s1, Def, Data { name: "x", data: 1 });
+        let s0 = scope_graph.add_scope_default();
+        let s1 = scope_graph.add_scope_default();
+        scope_graph.add_edge(s0, Lex, s1);
+        scope_graph.add_decl(s0, Def, Data { name: "x", data: 0 });
+        scope_graph.add_decl(s1, Def, Data { name: "x", data: 1 });
 
         compile_regex!(type Machine<Lbl> = Lex Def);
 
@@ -321,12 +378,12 @@ mod tests {
     #[test]
     fn test_regex_filter() {
         let mut scope_graph: ScopeGraph<Lbl, TData<usize>, UncheckedCompleteness> =
-            ScopeGraph::raw();
+            unsafe { ScopeGraph::raw() };
 
-        let s0 = scope_graph.new_scope(NoData);
-        let s1 = scope_graph.new_scope(NoData);
-        scope_graph.new_edge(s0, Lex, s1);
-        scope_graph.new_decl(s0, Def, Data { name: "x", data: 0 });
+        let s0 = scope_graph.add_scope_default();
+        let s1 = scope_graph.add_scope_default();
+        scope_graph.add_edge(s0, Lex, s1);
+        scope_graph.add_decl(s0, Def, Data { name: "x", data: 0 });
 
         compile_regex!(type Machine<Lbl> = Lex Def);
 
@@ -346,15 +403,15 @@ mod tests {
     #[test]
     fn test_shadow_applied() {
         let mut scope_graph: ScopeGraph<Lbl, TData<usize>, UncheckedCompleteness> =
-            ScopeGraph::raw();
+            unsafe { ScopeGraph::raw() };
 
-        let s0 = scope_graph.new_scope(NoData);
-        let s1 = scope_graph.new_scope(NoData);
-        let s2 = scope_graph.new_scope(NoData);
-        scope_graph.new_edge(s0, Imp, s1);
-        scope_graph.new_edge(s0, Lex, s2);
-        scope_graph.new_decl(s1, Def, Data { name: "x", data: 0 });
-        scope_graph.new_decl(s2, Def, Data { name: "x", data: 1 });
+        let s0 = scope_graph.add_scope_default();
+        let s1 = scope_graph.add_scope_default();
+        let s2 = scope_graph.add_scope_default();
+        scope_graph.add_edge(s0, Imp, s1);
+        scope_graph.add_edge(s0, Lex, s2);
+        scope_graph.add_decl(s1, Def, Data { name: "x", data: 0 });
+        scope_graph.add_decl(s2, Def, Data { name: "x", data: 1 });
 
         compile_regex!(type Machine<Lbl> = Lex Def);
 
@@ -377,19 +434,19 @@ mod tests {
     #[test]
     fn test_label_order_complex_raw() {
         let mut scope_graph: ScopeGraph<Lbl, TData<usize>, UncheckedCompleteness> =
-            ScopeGraph::raw();
+            unsafe { ScopeGraph::raw() };
 
-        let s0 = scope_graph.new_scope(NoData);
-        let s_with = scope_graph.new_scope(NoData);
-        let s_rec = scope_graph.new_scope(NoData);
-        let s_let = scope_graph.new_scope(NoData);
+        let s0 = scope_graph.add_scope_default();
+        let s_with = scope_graph.add_scope_default();
+        let s_rec = scope_graph.add_scope_default();
+        let s_let = scope_graph.add_scope_default();
 
-        scope_graph.new_edge(s_with, Lex, s0);
-        scope_graph.new_edge(s_with, Imp, s_rec);
-        scope_graph.new_edge(s_let, Lex, s_with);
+        scope_graph.add_edge(s_with, Lex, s0);
+        scope_graph.add_edge(s_with, Imp, s_rec);
+        scope_graph.add_edge(s_let, Lex, s_with);
 
-        scope_graph.new_decl(s_rec, Def, Data { name: "x", data: 1 });
-        scope_graph.new_decl(s_let, Def, Data { name: "x", data: 2 });
+        scope_graph.add_decl(s_rec, Def, Data { name: "x", data: 1 });
+        scope_graph.add_decl(s_let, Def, Data { name: "x", data: 2 });
 
         resolve_complex_unchecked(&mut scope_graph, s_let)
     }
@@ -399,26 +456,26 @@ mod tests {
         let mut scope_graph: ScopeGraph<Lbl, TData<usize>, ImplicitClose<Lbl>> =
             ScopeGraph::new(ImplicitClose::default());
 
-        let s0 = scope_graph.new_scope(NoData);
-        let s_with = scope_graph.new_scope(NoData);
-        let s_rec = scope_graph.new_scope(NoData);
-        let s_let = scope_graph.new_scope(NoData);
+        let s0 = scope_graph.add_scope_default();
+        let s_with = scope_graph.add_scope_default();
+        let s_rec = scope_graph.add_scope_default();
+        let s_let = scope_graph.add_scope_default();
 
         scope_graph
-            .new_edge(s_with, Lex, s0)
+            .add_edge(s_with, Lex, s0)
             .expect("edge closed unexpectedly");
         scope_graph
-            .new_edge(s_with, Imp, s_rec)
+            .add_edge(s_with, Imp, s_rec)
             .expect("edge closed unexpectedly");
         scope_graph
-            .new_edge(s_let, Lex, s_with)
+            .add_edge(s_let, Lex, s_with)
             .expect("edge closed unexpectedly");
 
         scope_graph
-            .new_decl(s_rec, Def, Data { name: "x", data: 1 })
+            .add_decl(s_rec, Def, Data { name: "x", data: 1 })
             .expect("edge closed unexpectedly");
         scope_graph
-            .new_decl(s_let, Def, Data { name: "x", data: 2 })
+            .add_decl(s_let, Def, Data { name: "x", data: 2 })
             .expect("edge closed unexpectedly");
 
         resolve_complex_unchecked(&mut scope_graph, s_let);
@@ -431,26 +488,26 @@ mod tests {
         let mut scope_graph: ScopeGraph<Lbl, TData<usize>, ExplicitClose<Lbl>> =
             ScopeGraph::new(ExplicitClose::default());
 
-        let s0 = scope_graph.new_scope_with::<[Lbl; 0]>(NoData, []);
-        let s_with = scope_graph.new_scope_with(NoData, [Lex, Imp]);
-        let s_rec = scope_graph.new_scope_with(NoData, [Def]);
-        let s_let = scope_graph.new_scope_with(NoData, [Lex, Def]);
+        let s0 = scope_graph.add_scope_default_closed();
+        let s_with = scope_graph.add_scope_default_with([Lex, Imp]);
+        let s_rec = scope_graph.add_scope_default_with([Def]);
+        let s_let = scope_graph.add_scope_default_with([Lex, Def]);
 
         scope_graph
-            .new_edge(s_with, Lex, s0)
+            .add_edge(s_with, Lex, s0)
             .expect("edge closed unexpectedly");
         scope_graph
-            .new_edge(s_with, Imp, s_rec)
+            .add_edge(s_with, Imp, s_rec)
             .expect("edge closed unexpectedly");
         scope_graph
-            .new_edge(s_let, Lex, s_with)
+            .add_edge(s_let, Lex, s_with)
             .expect("edge closed unexpectedly");
 
         scope_graph
-            .new_decl(s_rec, Def, Data { name: "x", data: 1 })
+            .add_decl(s_rec, Def, Data { name: "x", data: 1 })
             .expect("edge closed unexpectedly");
         scope_graph
-            .new_decl(s_let, Def, Data { name: "x", data: 2 })
+            .add_decl(s_let, Def, Data { name: "x", data: 2 })
             .expect("edge closed unexpectedly");
 
         scope_graph.close(s_with, &Lex);
diff --git a/scopegraphs-lib/src/resolve/mod.rs b/scopegraphs-lib/src/resolve/mod.rs
index 15e8e8f..15a5ec4 100644
--- a/scopegraphs-lib/src/resolve/mod.rs
+++ b/scopegraphs-lib/src/resolve/mod.rs
@@ -6,9 +6,13 @@ use std::sync::Arc;
 
 use super::Scope;
 
-pub mod containers; // FIXME: proper name (containers)
-pub mod topdown;
+pub mod containers;
+pub mod lookup;
 
+/// Representation of either a labeled edge or the special 'data' label.
+///
+/// Used to implement label orders. The `Data` label is there to support expressing preference
+/// between traversing an edge or resolving to the current node.
 #[derive(Hash, PartialEq, Eq)]
 pub enum EdgeOrData<LABEL> {
     Data,
@@ -33,14 +37,30 @@ impl<LABEL: Copy> Clone for EdgeOrData<LABEL> {
 
 impl<LABEL: Copy> Copy for EdgeOrData<LABEL> {}
 
+/// Unary predicate over `DATA`.
+///
+/// Used to select declarations that a query can resolve to.
 pub trait DataWellformedness<DATA>: for<'sg> Fn(&'sg DATA) -> bool {}
 impl<DATA, T> DataWellformedness<DATA> for T where for<'sg> T: Fn(&'sg DATA) -> bool {}
 
+/// Strict partial order on labels. Used to perform shadowing.
+///
+/// For example, suppose that in some scope `s`, declarations for some query are reachable via an
+/// `Lex` edge and an `Imp` edge (for lexical parent and import, respectively). When the label order
+/// Indicates `Lex < Imp` (i.e., declarations from a lexically enclosing scope have higher priority),
+/// the declaration over the `Imp` edge is shadowed, and will thus not be included in the
+/// environment. If `Imp < Lex`, imports have higher priority, and that one will be included.
+/// Otherwise, paths to both declarations are included in the environment.
 pub trait LabelOrder<LABEL>: Fn(&EdgeOrData<LABEL>, &EdgeOrData<LABEL>) -> bool {}
 impl<LABEL, T> LabelOrder<LABEL> for T where T: Fn(&EdgeOrData<LABEL>, &EdgeOrData<LABEL>) -> bool {}
 
-pub trait DataOrder<DATA>: for<'sg> Fn(&'sg DATA, &'sg DATA) -> bool {}
-impl<DATA, T> DataOrder<DATA> for T where for<'sg> T: Fn(&'sg DATA, &'sg DATA) -> bool {}
+/// Data equivalence relation.
+///
+/// Defines equivalence classes of declarations. Shadowing will only be applied with respect to
+/// declarations in the same equivalence class. That is, the shadowing explained in [`LabelOrder`]
+/// will only be applied if the declarations are equivalent.
+pub trait DataEquiv<DATA>: for<'sg> Fn(&'sg DATA, &'sg DATA) -> bool {}
+impl<DATA, T> DataEquiv<DATA> for T where for<'sg> T: Fn(&'sg DATA, &'sg DATA) -> bool {}
 
 #[derive(Hash, PartialEq, Eq, Debug)]
 enum InnerPath<LABEL> {
@@ -54,6 +74,7 @@ enum InnerPath<LABEL> {
     },
 }
 
+/// Path (alternating sequence of scopes and labels) in a scope graph.
 #[derive(Clone)]
 pub struct Path<LABEL> {
     inner_path: Arc<InnerPath<LABEL>>,
@@ -110,6 +131,7 @@ where
     }
 }
 
+/// A path in the scope graph, including the data of the target of the path.
 #[derive(Hash, PartialEq, Eq, Debug, Clone)]
 pub struct ResolvedPath<'sg, LABEL, DATA> {
     path: Path<LABEL>,
@@ -127,6 +149,7 @@ impl<'sg, LABEL, DATA> ResolvedPath<'sg, LABEL, DATA> {
 }
 
 impl<LABEL> Path<LABEL> {
+    /// Creates a new path that contains of a single scope.
     pub fn new(source: Scope) -> Self {
         Self {
             inner_path: Arc::new(InnerPath::Start { source }),
@@ -134,6 +157,7 @@ impl<LABEL> Path<LABEL> {
         }
     }
 
+    /// Returns the last scope in the path.
     pub fn target(&self) -> Scope {
         match self.inner_path.as_ref() {
             InnerPath::Start { source } => *source,
@@ -141,6 +165,9 @@ impl<LABEL> Path<LABEL> {
         }
     }
 
+    /// Extends the path with a new edge.
+    ///
+    /// Returns `None` if the resulting path would contain a cycle.
     pub fn step(&self, label: LABEL, target: Scope) -> Option<Self> {
         if self.scopes.search(&target) {
             None
@@ -159,11 +186,13 @@ impl<LABEL> Path<LABEL> {
         }
     }
 
+    /// Creates a resolved path from this path.
     pub fn resolve<DATA>(self, data: &DATA) -> ResolvedPath<'_, LABEL, DATA> {
         ResolvedPath { path: self, data }
     }
 }
 
+/// Representation of an environment (i.e., a collection of resolved paths).
 // For now, we stick with hashmaps because they are easy.
 // We might however want to change that in the future, because:
 // - we currently create a lot of new hashmaps, which is not really efficient
@@ -189,10 +218,12 @@ impl<LABEL, DATA> Default for Env<'_, LABEL, DATA> {
 }
 
 impl<'sg, LABEL, DATA> Env<'sg, LABEL, DATA> {
+    /// Creates an empty environemnt.
     pub fn new() -> Self {
         Self(HashSet::new())
     }
 
+    /// Create an iterator over all paths in the environment.
     pub fn iter<'a>(&'a self) -> impl Iterator<Item = &'a ResolvedPath<'sg, LABEL, DATA>> + 'a {
         self.0.iter()
     }
@@ -202,16 +233,19 @@ impl<'sg, LABEL, DATA> Env<'sg, LABEL, DATA>
 where
     ResolvedPath<'sg, LABEL, DATA>: Eq + Hash,
 {
+    /// Create an environment with a single path.
     pub fn single(path: ResolvedPath<'sg, LABEL, DATA>) -> Self {
         let mut env = Env::new();
         env.insert(path);
         env
     }
 
+    /// Insert a path in the environment.
     pub fn insert(&mut self, path: ResolvedPath<'sg, LABEL, DATA>) {
         self.0.insert(path);
     }
 
+    /// Add all paths in `other` to the current environment.
     pub fn merge(&mut self, other: Self) {
         self.0.extend(other.0)
     }
@@ -223,11 +257,7 @@ where
     ResolvedPath<'sg, LABEL, DATA>: Eq + Hash,
 {
     fn from_iter<T: IntoIterator<Item = ResolvedPath<'sg, LABEL, DATA>>>(iter: T) -> Self {
-        let mut env = Env::new();
-        for path in iter.into_iter() {
-            env.insert(path)
-        }
-        env
+        Env(HashSet::from_iter(iter))
     }
 }
 
@@ -236,10 +266,6 @@ where
     ResolvedPath<'sg, LABEL, DATA>: Eq + Hash,
 {
     fn from_iter<T: IntoIterator<Item = Env<'sg, LABEL, DATA>>>(iter: T) -> Self {
-        let mut env = Env::new();
-        for sub_env in iter.into_iter() {
-            env.merge(sub_env)
-        }
-        env
+        iter.into_iter().flatten().collect()
     }
 }