Merge #2385

2385: Some docs r=matklad a=matklad



Co-authored-by: Aleksey Kladov <[email protected]>

11 files changed, 43 insertions, 38 deletions

diff --git a/crates/ra_hir_def/src/body.rs b/crates/ra_hir_def/src/body.rs
index 1589085b5..c06997cf1 100644
--- a/crates/ra_hir_def/src/body.rs
+++ b/crates/ra_hir_def/src/body.rs
@@ -82,7 +82,7 @@ impl Expander {
     }
 
     fn resolve_path_as_macro(&self, db: &impl DefDatabase, path: &Path) -> Option<MacroDefId> {
-        self.crate_def_map.resolve_path(db, self.module.module_id, path).0.get_macros()
+        self.crate_def_map.resolve_path(db, self.module.module_id, path).0.take_macros()
     }
 }
 
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/lib.rs b/crates/ra_hir_def/src/lib.rs
index f60feb5fa..f63c3dd64 100644
--- a/crates/ra_hir_def/src/lib.rs
+++ b/crates/ra_hir_def/src/lib.rs
@@ -8,20 +8,23 @@
 //! actually true.
 
 pub mod db;
+
 pub mod attr;
 pub mod path;
 pub mod type_ref;
 pub mod builtin_type;
-pub mod adt;
 pub mod diagnostics;
-pub mod expr;
-pub mod body;
-pub mod generics;
-pub mod resolver;
+pub mod per_ns;
+
+pub mod adt;
 pub mod data;
+pub mod generics;
 pub mod lang_item;
 pub mod docs;
-pub mod per_ns;
+
+pub mod expr;
+pub mod body;
+pub mod resolver;
 
 mod trace;
 mod nameres;
diff --git a/crates/ra_hir_def/src/nameres.rs b/crates/ra_hir_def/src/nameres.rs
index f6cf59c5f..5919771b0 100644
--- a/crates/ra_hir_def/src/nameres.rs
+++ b/crates/ra_hir_def/src/nameres.rs
@@ -169,7 +169,7 @@ impl ModuleScope {
     pub fn macros<'a>(&'a self) -> impl Iterator<Item = (&'a Name, MacroDefId)> + 'a {
         self.items
             .iter()
-            .filter_map(|(name, res)| res.def.get_macros().map(|macro_| (name, macro_)))
+            .filter_map(|(name, res)| res.def.take_macros().map(|macro_| (name, macro_)))
     }
 
     /// Iterate over all legacy textual scoped macros visable at the end of the module
diff --git a/crates/ra_hir_def/src/nameres/collector.rs b/crates/ra_hir_def/src/nameres/collector.rs
index 7a5f90327..df01a20e1 100644
--- a/crates/ra_hir_def/src/nameres/collector.rs
+++ b/crates/ra_hir_def/src/nameres/collector.rs
@@ -476,7 +476,7 @@ where
                 path,
             );
 
-            if let Some(def) = resolved_res.resolved_def.get_macros() {
+            if let Some(def) = resolved_res.resolved_def.take_macros() {
                 let call_id = self.db.intern_macro(MacroCallLoc { def, ast_id: *ast_id });
                 resolved.push((*module_id, call_id, def));
                 res = ReachedFixedPoint::No;
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 626ebffdc..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};
 
@@ -66,7 +66,7 @@ pub enum PathKind {
 
 impl Path {
     /// Calls `cb` with all paths, represented by this use item.
-    pub fn expand_use_item(
+    pub(crate) fn expand_use_item(
         item_src: Source<ast::UseItem>,
         hygiene: &Hygiene,
         mut cb: impl FnMut(Path, &ast::UseTree, bool, Option<Name>),
@@ -76,7 +76,10 @@ impl Path {
         }
     }
 
-    pub fn from_simple_segments(kind: PathKind, segments: impl IntoIterator<Item = Name>) -> Path {
+    pub(crate) fn from_simple_segments(
+        kind: PathKind,
+        segments: impl IntoIterator<Item = Name>,
+    ) -> Path {
         Path {
             kind,
             segments: segments
@@ -94,7 +97,7 @@ impl Path {
 
     /// Converts an `ast::Path` to `Path`. Works with use trees.
     /// It correctly handles `$crate` based path from macro call.
-    pub fn from_src(mut path: ast::Path, hygiene: &Hygiene) -> Option<Path> {
+    pub(crate) fn from_src(mut path: ast::Path, hygiene: &Hygiene) -> Option<Path> {
         let mut kind = PathKind::Plain;
         let mut segments = Vec::new();
         loop {
@@ -227,7 +230,7 @@ impl Path {
 }
 
 impl GenericArgs {
-    pub fn from_ast(node: ast::TypeArgList) -> Option<GenericArgs> {
+    pub(crate) fn from_ast(node: ast::TypeArgList) -> Option<GenericArgs> {
         let mut args = Vec::new();
         for type_arg in node.type_args() {
             let type_ref = TypeRef::from_ast_opt(type_arg.type_ref());
diff --git a/crates/ra_hir_def/src/per_ns.rs b/crates/ra_hir_def/src/per_ns.rs
index 717ed1ef9..06ef6c9fc 100644
--- a/crates/ra_hir_def/src/per_ns.rs
+++ b/crates/ra_hir_def/src/per_ns.rs
@@ -44,10 +44,6 @@ impl PerNs {
         self.types.is_none() && self.values.is_none() && self.macros.is_none()
     }
 
-    pub fn is_all(&self) -> bool {
-        self.types.is_some() && self.values.is_some() && self.macros.is_some()
-    }
-
     pub fn take_types(self) -> Option<ModuleDefId> {
         self.types
     }
@@ -56,14 +52,10 @@ impl PerNs {
         self.values
     }
 
-    pub fn get_macros(&self) -> Option<MacroDefId> {
+    pub fn take_macros(self) -> Option<MacroDefId> {
         self.macros
     }
 
-    pub fn only_macros(&self) -> PerNs {
-        PerNs { types: None, values: None, macros: self.macros }
-    }
-
     pub fn or(self, other: PerNs) -> PerNs {
         PerNs {
             types: self.types.or(other.types),
diff --git a/crates/ra_hir_def/src/resolver.rs b/crates/ra_hir_def/src/resolver.rs
index 4ff0a091b..7182b8a4d 100644
--- a/crates/ra_hir_def/src/resolver.rs
+++ b/crates/ra_hir_def/src/resolver.rs
@@ -308,7 +308,7 @@ impl Resolver {
 
     pub fn resolve_path_as_macro(&self, db: &impl DefDatabase, path: &Path) -> Option<MacroDefId> {
         let (item_map, module) = self.module()?;
-        item_map.resolve_path(db, module, path).0.get_macros()
+        item_map.resolve_path(db, module, path).0.take_macros()
     }
 
     pub fn process_all_names(&self, db: &impl DefDatabase, f: &mut dyn FnMut(Name, ScopeDef)) {
diff --git a/crates/ra_hir_def/src/type_ref.rs b/crates/ra_hir_def/src/type_ref.rs
index 8af061116..5f10e9a88 100644
--- a/crates/ra_hir_def/src/type_ref.rs
+++ b/crates/ra_hir_def/src/type_ref.rs
@@ -64,7 +64,7 @@ pub enum TypeBound {
 
 impl TypeRef {
     /// Converts an `ast::TypeRef` to a `hir::TypeRef`.
-    pub fn from_ast(node: ast::TypeRef) -> Self {
+    pub(crate) fn from_ast(node: ast::TypeRef) -> Self {
         match node {
             ast::TypeRef::ParenType(inner) => TypeRef::from_ast_opt(inner.type_ref()),
             ast::TypeRef::TupleType(inner) => {
@@ -113,7 +113,7 @@ impl TypeRef {
         }
     }
 
-    pub fn from_ast_opt(node: Option<ast::TypeRef>) -> Self {
+    pub(crate) fn from_ast_opt(node: Option<ast::TypeRef>) -> Self {
         if let Some(node) = node {
             TypeRef::from_ast(node)
         } else {
@@ -121,7 +121,7 @@ impl TypeRef {
         }
     }
 
-    pub fn unit() -> TypeRef {
+    pub(crate) fn unit() -> TypeRef {
         TypeRef::Tuple(Vec::new())
     }
 }
@@ -135,7 +135,7 @@ pub(crate) fn type_bounds_from_ast(type_bounds_opt: Option<ast::TypeBoundList>)
 }
 
 impl TypeBound {
-    pub fn from_ast(node: ast::TypeBound) -> Self {
+    pub(crate) fn from_ast(node: ast::TypeBound) -> Self {
         match node.kind() {
             ast::TypeBoundKind::PathType(path_type) => {
                 let path = match path_type.path() {