Add basic name-analysis phase documentation.

src/name_analysis/mod.rs

@@ -1,3 +1,24 @@
+/*!
+# Name Analysis
+
+There are two phases in name analysis.
+
+## 1. Gather
+
+The gather phases has three responsibilities:
+
+1. Add all declared symbols to the symbol table.
+2. Set the `scope_id` property of all identifiers and fully-qualified-names.
+3. For the main identifiers of `UseStatement`s (i.e., the last identifier in the `UseStatement`):
+   set a 'linking' symbol on the identifier, which will later be filled in with the linked-to
+   symbol (probably in another file, or from the standard library).
+
+## 2. Resolve
+
+The resolve phase has one main responsibility: resolve all references based on the identifier's
+`scope_id` property.
+*/
+
 use crate::ast::named::Named;
 use crate::ast::CompilationUnit;
 use crate::diagnostic::DmDiagnostic;
@@ -158,7 +179,7 @@ mod tests {
             "main.dm",
             indoc! {"
                 platform fn println(msg: Any) -> Void;
-            "}
+            "},
         )]);
         let mut symbol_table = SymbolTable::new();
         add_std_core_symbols(&mut symbol_table).expect("Failed to add std::core symbols.");