4 files changed, 18 insertions, 11 deletions

diff --git a/crates/ra_hir_def/src/data.rs b/crates/ra_hir_def/src/data.rs
index 81a8ec18d..68bea34df 100644
--- a/crates/ra_hir_def/src/data.rs
+++ b/crates/ra_hir_def/src/data.rs
@@ -200,18 +200,17 @@ pub struct ConstData {
 impl ConstData {
     pub(crate) fn const_data_query(db: &impl DefDatabase, konst: ConstId) -> Arc<ConstData> {
         let node = konst.lookup(db).source(db).value;
-        const_data_for(&node)
+        Arc::new(ConstData::new(&node))
     }
 
     pub(crate) fn static_data_query(db: &impl DefDatabase, konst: StaticId) -> Arc<ConstData> {
         let node = konst.lookup(db).source(db).value;
-        const_data_for(&node)
+        Arc::new(ConstData::new(&node))
     }
-}
 
-fn const_data_for<N: NameOwner + TypeAscriptionOwner>(node: &N) -> Arc<ConstData> {
-    let name = node.name().map(|n| n.as_name());
-    let type_ref = TypeRef::from_ast_opt(node.ascribed_type());
-    let sig = ConstData { name, type_ref };
-    Arc::new(sig)
+    fn new<N: NameOwner + TypeAscriptionOwner>(node: &N) -> ConstData {
+        let name = node.name().map(|n| n.as_name());
+        let type_ref = TypeRef::from_ast_opt(node.ascribed_type());
+        ConstData { name, type_ref }
+    }
 }
diff --git a/crates/ra_hir_def/src/docs.rs b/crates/ra_hir_def/src/docs.rs
index 225511428..90a8627bc 100644
--- a/crates/ra_hir_def/src/docs.rs
+++ b/crates/ra_hir_def/src/docs.rs
@@ -1,4 +1,7 @@
-//! FIXME: write short doc here
+//! Defines hir documentation.
+//!
+//! This really shouldn't exist, instead, we should deshugar doc comments into attributes, see
+//! https://github.com/rust-analyzer/rust-analyzer/issues/2148#issuecomment-550519102
 
 use std::sync::Arc;
 
diff --git a/crates/ra_hir_def/src/nameres/raw.rs b/crates/ra_hir_def/src/nameres/raw.rs
index 198578753..2ec84f2cc 100644
--- a/crates/ra_hir_def/src/nameres/raw.rs
+++ b/crates/ra_hir_def/src/nameres/raw.rs
@@ -1,4 +1,9 @@
-//! FIXME: write short doc here
+//! Lowers syntax tree of a rust file into a raw representation of containing
+//! items, *without* attaching them to a module structure.
+//!
+//! That is, raw items don't have semantics, just as syntax, but, unlike syntax,
+//! they don't change with trivial source code edits, making them a great tool
+//! for building salsa recomputation firewalls.
 
 use std::{ops::Index, sync::Arc};
 
diff --git a/crates/ra_hir_def/src/path.rs b/crates/ra_hir_def/src/path.rs
index 94f6a27bc..7b2723d57 100644
--- a/crates/ra_hir_def/src/path.rs
+++ b/crates/ra_hir_def/src/path.rs
@@ -1,4 +1,4 @@
-//! FIXME: write short doc here
+//! A desugared representation of paths like `crate::foo` or `<Type as Trait>::bar`.
 
 use std::{iter, sync::Arc};