The first approximation of name resolution (#22)

* The first approximation of name resolution

The first attempt to write something useful about the name resolution.
As the TODO section says, his is not finished thing, but it might
hopefully be useful to someone already.

src/name-resolution.md

@@ -1 +1,107 @@
 # Name resolution
+
+The name resolution is a separate pass in the compiler. Its input is the syntax
+tree, produced by parsing input files. It produces links from all the names in
+the source to relevant places where the name was introduced. It also generates
+helpful error messages, like typo suggestions or traits to import.
+
+The name resolution lives in the `librustc_resolve` crate, with the meat in
+`lib.rs` and some helpers or symbol-type specific logic in the other modules.
+
+## Namespaces
+
+Different kind of symbols live in different namespaces ‒ eg. types don't
+clash with variables. This usually doesn't happen, because variables start with
+lower-case letter while types with upper case one, but this is only a
+convention. This is legal Rust code that'll compile (with warnings):
+
+```rust
+type x = u32;
+let x: x = 1;
+let y: x = 2; // See? x is still a type here.
+```
+
+To cope with this, and with slightly different scoping rules for these
+namespaces, the resolver keeps them separated and builds separate structures for
+them.
+
+In other words, when the code talks about namespaces, it doesn't mean the module
+hierarchy, it's types vs. values vs. macros.
+
+## Scopes and ribs
+
+A name is visible only in certain area in the source code. This forms a
+hierarchical structure, but not necessarily a simple one ‒ if one scope is part
+of another, it doesn't mean the name visible in the outer one is also visible in
+the inner one, or that it refers to the same thing.
+
+To cope with that, the compiler introduces the concept of Ribs. This is
+abstraction of a scope. Every time the set of visible names potentially changes,
+a new rib is pushed onto a stack. The places where this can happen includes for
+example:
+
+* The obvious places ‒ curly braces enclosing a block, function boundaries,
+  modules.
+* Introducing a let binding ‒ this can shadow another binding with the same
+  name.
+* Macro expansion border ‒ to cope with macro hygiene.
+
+When searching for a name, the stack of ribs is traversed from the innermost
+outwards. This helps to find the closest meaning of the name (the one not
+shadowed by anything else). The transition to outer rib may also change the
+rules what names are usable ‒ if there are nested functions (not closures), the
+inner one can't access parameters and local bindings of the outer one, even
+though they should be visible by ordinary scoping rules. An example:
+
+```rust
+fn do_something<T: Default>(val: T) { // <- New rib in both types and values (1)
+    // `val` is accessible, as is the helper function
+    // `T` is accessible
+    let helper = || { // New rib on `helper` (2) and another on the block (3)
+        // `val` is accessible here
+    }; // End of (3)
+    // `val` is accessible, `helper` variable shadows `helper` function
+    fn helper() { // <- New rib in both types and values (4)
+        // `val` is not accessible here, (4) is not transparent for locals)
+        // `T` is not accessible here
+    } // End of (4)
+    let val = T::default(); // New rib (5)
+    // `val` is the variable, not the parameter here
+} // End of (5), (2) and (1)
+```
+
+Because the rules for different namespaces are a bit different, each namespace
+has its own independent rib stack that is constructed in parallel to the others.
+
+## Overall strategy
+
+To perform the name resolution of the whole crate, the syntax tree is traversed
+top-down and every encountered name is resolved. This works for most kinds of
+names, because at the point of use of a name it is already introduced in the Rib
+hierarchy.
+
+There are some exceptions to this. Items are bit tricky, because they can be
+used even before encountered ‒ therefore every block needs to be first scanned
+for items to fill in its Rib.
+
+Other, even more problematic ones, are imports which need recursive fixed-point
+resolution and macros, that need to be resolved and expanded before the rest of
+the code can be processed.
+
+Therefore, the resolution is performed in multiple stages.
+
+## TODO:
+
+This is a result of the first pass of learning the code. It is definitely
+incomplete and not detailed enough. It also might be inaccurate in places.
+Still, it probably provides useful first guidepost to what happens in there.
+
+* What exactly does it link to and how is that published and consumed by
+  following stages of compilation?
+* Who calls it and how it is actually used.
+* Is it a pass and then the result is only used, or can it be computed
+  incrementally (eg. for RLS)?
+* The overall strategy description is a bit vague.
+* Where does the name `Rib` come from?
+* Does this thing have its own tests, or is it tested only as part of some e2e
+  testing?