diff --git a/crates/ra_hir/src/ids.rs b/crates/ra_hir/src/ids.rs
new file mode 100644
index 00000000000..881303861da
--- /dev/null
+++ b/crates/ra_hir/src/ids.rs
@@ -0,0 +1,32 @@
+use crate::{FileId, MacroCallId};
+
+/// hir makes a heavy use of ids: integer (u32) handlers to various things. You
+/// can think of id as a pointer (but without a lifetime) or a file descriptor
+/// (but for hir objects).
+///
+/// This module defines a bunch of ids we are using. The most important ones are
+/// probably `HirFileId` and `DefId`.
+
+/// Input to the analyzer is a set of file, where each file is indetified by
+/// `FileId` and contains source code. However, another source of source code in
+/// Rust are macros: each macro can be thought of as producing a "temporary
+/// file". To assign id to such file, we use the id of a macro call that
+/// produced the file. So, a `HirFileId` is either a `FileId` (source code
+/// written by user), or a `MacroCallId` (source code produced by macro).
+///
+/// What is a `MacroCallId`? Simplifying, it's a `HirFileId` of a file containin
+/// the call plus the offset of the macro call in the file. Note that this is a
+/// recursive definition! Nethetheless, size_of of `HirFileId` is finite
+/// (because everything bottoms out at the real `FileId`) and small
+/// (`MacroCallId` uses location interner).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum MFileId {
+    File(FileId),
+    Macro(MacroCallId),
+}
+
+impl From<FileId> for MFileId {
+    fn from(file_id: FileId) -> MFileId {
+        MFileId::File(file_id)
+    }
+}
diff --git a/crates/ra_hir/src/lib.rs b/crates/ra_hir/src/lib.rs
index 1219b9fbab1..8d3a026d5e8 100644
--- a/crates/ra_hir/src/lib.rs
+++ b/crates/ra_hir/src/lib.rs
@@ -22,6 +22,7 @@ macro_rules! ctry {
 mod arena;
 pub mod source_binder;
 
+mod ids;
 mod macros;
 mod name;
 mod krate;
@@ -46,6 +47,7 @@ macro_rules! ctry {
     path::{Path, PathKind},
     name::Name,
     krate::Crate,
+    ids::MFileId,
     macros::{MacroDef, MacroInput, MacroExpansion, MacroCallId, MacroCallLoc},
     module::{Module, ModuleId, Problem, nameres::{ItemMap, PerNs, Namespace}, ModuleScope, Resolution},
     function::{Function, FnScopes},
@@ -55,20 +57,6 @@ macro_rules! ctry {
 
 pub use self::function::FnSignatureInfo;
 
-/// An `MFileId` is like a `FileId`, but it can also refer to code generated by
-/// macros.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-pub enum MFileId {
-    File(FileId),
-    Macro(MacroCallId),
-}
-
-impl From<FileId> for MFileId {
-    fn from(file_id: FileId) -> MFileId {
-        MFileId::File(file_id)
-    }
-}
-
 /// Def's are a core concept of hir. A `Def` is an Item (function, module, etc)
 /// in a specific module.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]