1 files changed, 15 insertions, 9 deletions

diff --git a/crates/ra_hir/src/nameres.rs b/crates/ra_hir/src/nameres.rs
index 17602ee6b..edd2f25f7 100644
--- a/crates/ra_hir/src/nameres.rs
+++ b/crates/ra_hir/src/nameres.rs
@@ -10,12 +10,12 @@
 ///
 /// Computing `CrateDefMap` can be partitioned into several logically
 /// independent "phases". The phases are mutually recursive though, there's no
-/// stric ordering.
+/// strict ordering.
 ///
 /// ## Collecting RawItems
 ///
 ///  This happens in the `raw` module, which parses a single source file into a
-///  set of top-level items. Nested importa are desugared to flat imports in
+///  set of top-level items. Nested imports are desugared to flat imports in
 ///  this phase. Macro calls are represented as a triple of (Path, Option<Name>,
 ///  TokenTree).
 ///
@@ -24,22 +24,28 @@
 /// This happens in the `collector` module. In this phase, we recursively walk
 /// tree of modules, collect raw items from submodules, populate module scopes
 /// with defined items (so, we assign item ids in this phase) and record the set
-/// of unresovled imports and macros.
+/// of unresolved imports and macros.
 ///
-/// While we walk tree of modules, we also record macro_rules defenitions and
+/// While we walk tree of modules, we also record macro_rules definitions and
 /// expand calls to macro_rules defined macros.
 ///
 /// ## Resolving Imports
 ///
-/// TBD
+/// We maintain a list of currently unresolved imports. On every iteration, we
+/// try to resolve some imports from this list. If the import is resolved, we
+/// record it, by adding an item to current module scope and, if necessary, by
+/// recursively populating glob imports.
 ///
 /// ## Resolving Macros
 ///
-/// While macro_rules from the same crate use a global mutable namespace, macros
-/// from other crates (including proc-macros) can be used with `foo::bar!`
-/// syntax.
+/// macro_rules from the same crate use a global mutable namespace. We expand
+/// them immediately, when we collect modules.
 ///
-/// TBD;
+/// Macros from other crates (including proc-macros) can be used with
+/// `foo::bar!` syntax. We handle them similarly to imports. There's a list of
+/// unexpanded macros. On every iteration, we try to resolve each macro call
+/// path and, upon success, we run macro expansion and "collect module" phase
+/// on the result
 
 mod per_ns;
 mod raw;