20 files changed, 72 insertions, 40 deletions

diff --git a/crates/hir/src/db.rs b/crates/hir/src/db.rs
index ffc8155b9..19898f683 100644
--- a/crates/hir/src/db.rs
+++ b/crates/hir/src/db.rs
@@ -1,5 +1,8 @@
-//! FIXME: write short doc here
-
+//! Re-exports various subcrates databases so that the calling code can depend
+//! only on `hir`. This breaks abstraction boundary a bit, it would be cool if
+//! we didn't do that.
+//!
+//! But we need this for at least LRU caching at the query level.
 pub use hir_def::db::*;
 pub use hir_expand::db::{
     AstDatabase, AstDatabaseStorage, AstIdMapQuery, HygieneFrameQuery, InternMacroQuery,
diff --git a/crates/hir/src/diagnostics.rs b/crates/hir/src/diagnostics.rs
index b1ebba516..414c3f35e 100644
--- a/crates/hir/src/diagnostics.rs
+++ b/crates/hir/src/diagnostics.rs
@@ -1,4 +1,8 @@
-//! FIXME: write short doc here
+//! Re-export diagnostics such that clients of `hir` don't have to depend on
+//! low-level crates.
+//!
+//! This probably isn't the best way to do this -- ideally, diagnistics should
+//! be expressed in terms of hir types themselves.
 pub use hir_def::diagnostics::{
     InactiveCode, UnresolvedMacroCall, UnresolvedModule, UnresolvedProcMacro,
 };
diff --git a/crates/ide/src/display/navigation_target.rs b/crates/ide/src/display/navigation_target.rs
index 2079c22a3..b75ec411c 100644
--- a/crates/ide/src/display/navigation_target.rs
+++ b/crates/ide/src/display/navigation_target.rs
@@ -1,4 +1,4 @@
-//! FIXME: write short doc here
+//! See [`NavigationTarget`].
 
 use std::fmt;
 
diff --git a/crates/ide/src/folding_ranges.rs b/crates/ide/src/folding_ranges.rs
index a03988778..b893c1c54 100755
--- a/crates/ide/src/folding_ranges.rs
+++ b/crates/ide/src/folding_ranges.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use rustc_hash::FxHashSet;
 
 use syntax::{
@@ -29,6 +27,10 @@ pub struct Fold {
     pub kind: FoldKind,
 }
 
+// Feature: Folding
+//
+// Defines folding regions for curly braced blocks, runs of consecutive import
+// statements, and `region` / `endregion` comment markers.
 pub(crate) fn folding_ranges(file: &SourceFile) -> Vec<Fold> {
     let mut res = vec![];
     let mut visited_comments = FxHashSet::default();
diff --git a/crates/ide_assists/src/assist_context.rs b/crates/ide_assists/src/assist_context.rs
index 20754a02a..8fc40f9bd 100644
--- a/crates/ide_assists/src/assist_context.rs
+++ b/crates/ide_assists/src/assist_context.rs
@@ -1,4 +1,4 @@
-//! See `AssistContext`
+//! See [`AssistContext`].
 
 use std::mem;
 
diff --git a/crates/ide_assists/src/path_transform.rs b/crates/ide_assists/src/path_transform.rs
index 6ec318c4c..48a7fa06a 100644
--- a/crates/ide_assists/src/path_transform.rs
+++ b/crates/ide_assists/src/path_transform.rs
@@ -1,4 +1,5 @@
-//! See `PathTransform`
+//! See [`PathTransform`].
+
 use hir::{HirDisplay, SemanticsScope};
 use ide_db::helpers::mod_path_to_ast;
 use rustc_hash::FxHashMap;
diff --git a/crates/profile/src/lib.rs b/crates/profile/src/lib.rs
index a31fb8f43..7cd01a7df 100644
--- a/crates/profile/src/lib.rs
+++ b/crates/profile/src/lib.rs
@@ -124,5 +124,5 @@ impl Drop for CpuSpan {
 }
 
 pub fn memory_usage() -> MemoryUsage {
-    MemoryUsage::current()
+    MemoryUsage::now()
 }
diff --git a/crates/profile/src/memory_usage.rs b/crates/profile/src/memory_usage.rs
index cb4e54447..2917ded60 100644
--- a/crates/profile/src/memory_usage.rs
+++ b/crates/profile/src/memory_usage.rs
@@ -1,4 +1,6 @@
-//! FIXME: write short doc here
+//! Like [`std::time::Instant`], but for memory.
+//!
+//! Measures the total size of all currently allocated objects.
 use std::fmt;
 
 use cfg_if::cfg_if;
@@ -22,7 +24,7 @@ impl std::ops::Sub for MemoryUsage {
 }
 
 impl MemoryUsage {
-    pub fn current() -> MemoryUsage {
+    pub fn now() -> MemoryUsage {
         cfg_if! {
             if #[cfg(all(feature = "jemalloc", not(target_env = "msvc")))] {
                 jemalloc_ctl::epoch::advance().unwrap();
diff --git a/crates/profile/src/stop_watch.rs b/crates/profile/src/stop_watch.rs
index cb6915d45..112d03a9c 100644
--- a/crates/profile/src/stop_watch.rs
+++ b/crates/profile/src/stop_watch.rs
@@ -44,7 +44,7 @@ impl StopWatch {
     }
     pub fn memory(mut self, yes: bool) -> StopWatch {
         if yes {
-            self.memory = Some(MemoryUsage::current());
+            self.memory = Some(MemoryUsage::now());
         }
         self
     }
@@ -58,7 +58,7 @@ impl StopWatch {
         #[cfg(not(target_os = "linux"))]
         let instructions = None;
 
-        let memory = self.memory.map(|it| MemoryUsage::current() - it);
+        let memory = self.memory.map(|it| MemoryUsage::now() - it);
         StopWatchSpan { time, instructions, memory }
     }
 }
diff --git a/crates/project_model/src/cargo_workspace.rs b/crates/project_model/src/cargo_workspace.rs
index 4a4996cf4..ad705c752 100644
--- a/crates/project_model/src/cargo_workspace.rs
+++ b/crates/project_model/src/cargo_workspace.rs
@@ -1,4 +1,4 @@
-//! FIXME: write short doc here
+//! See [`CargoWorkspace`].
 
 use std::path::PathBuf;
 use std::{convert::TryInto, ops, process::Command, sync::Arc};
@@ -12,10 +12,9 @@ use rustc_hash::FxHashMap;
 use serde::Deserialize;
 use serde_json::from_value;
 
-use crate::build_data::BuildDataConfig;
-use crate::utf8_stdout;
+use crate::{build_data::BuildDataConfig, utf8_stdout};
 
-/// `CargoWorkspace` represents the logical structure of, well, a Cargo
+/// [`CargoWorkspace`] represents the logical structure of, well, a Cargo
 /// workspace. It pretty closely mirrors `cargo metadata` output.
 ///
 /// Note that internally, rust analyzer uses a different structure:
diff --git a/crates/project_model/src/lib.rs b/crates/project_model/src/lib.rs
index a5b35ed95..8c6cf94c2 100644
--- a/crates/project_model/src/lib.rs
+++ b/crates/project_model/src/lib.rs
@@ -1,4 +1,19 @@
-//! FIXME: write short doc here
+//! In rust-analyzer, we maintain a strict separation between pure abstract
+//! semantic project model and a concrete model of a particular build system.
+//!
+//! Pure model is represented by the [`base_db::CrateGraph`] from another crate.
+//!
+//! In this crate, we are conserned with "real world" project models.
+//!
+//! Specifically, here we have a representation for a Cargo project
+//! ([`CargoWorkspace`]) and for manually specified layout ([`ProjectJson`]).
+//!
+//! Roughly, the things we do here are:
+//!
+//! * Project discovery (where's the relevant Cargo.toml for the current dir).
+//! * Custom build steps (`build.rs` code generation and compilation of
+//!   procedural macros).
+//! * Lowering of concrete model to a [`base_db::CrateGraph`]
 
 mod cargo_workspace;
 mod cfg_flag;
diff --git a/crates/project_model/src/project_json.rs b/crates/project_model/src/project_json.rs
index 41a2ac03e..e8f1aca61 100644
--- a/crates/project_model/src/project_json.rs
+++ b/crates/project_model/src/project_json.rs
@@ -1,4 +1,9 @@
-//! FIXME: write short doc here
+//! `rust-project.json` file format.
+//!
+//! This format is spiritually a serialization of [`base_db::CrateGraph`]. The
+//! idea here is that people who do not use Cargo, can instead teach their build
+//! system to generate `rust-project.json` which can be ingested by
+//! rust-analyzer.
 
 use std::path::PathBuf;
 
diff --git a/crates/syntax/fuzz/fuzz_targets/parser.rs b/crates/syntax/fuzz/fuzz_targets/parser.rs
index 386768343..f80e13002 100644
--- a/crates/syntax/fuzz/fuzz_targets/parser.rs
+++ b/crates/syntax/fuzz/fuzz_targets/parser.rs
@@ -1,4 +1,4 @@
-//! FIXME: write short doc here
+//! Fuzzing for from-scratch parsing.
 
 #![no_main]
 use libfuzzer_sys::fuzz_target;
diff --git a/crates/syntax/fuzz/fuzz_targets/reparse.rs b/crates/syntax/fuzz/fuzz_targets/reparse.rs
index 5ac99fdaf..f865ce8d6 100644
--- a/crates/syntax/fuzz/fuzz_targets/reparse.rs
+++ b/crates/syntax/fuzz/fuzz_targets/reparse.rs
@@ -1,4 +1,4 @@
-//! FIXME: write short doc here
+//! Fuzzing for incremental parsing.
 
 #![no_main]
 use libfuzzer_sys::fuzz_target;
diff --git a/crates/syntax/src/algo.rs b/crates/syntax/src/algo.rs
index 241713c48..8d7a77b50 100644
--- a/crates/syntax/src/algo.rs
+++ b/crates/syntax/src/algo.rs
@@ -1,4 +1,4 @@
-//! FIXME: write short doc here
+//! Collection of assorted algorithms for syntax trees.
 
 use std::{hash::BuildHasherDefault, ops::RangeInclusive};
 
diff --git a/crates/syntax/src/fuzz.rs b/crates/syntax/src/fuzz.rs
index aa84239d2..256999fe0 100644
--- a/crates/syntax/src/fuzz.rs
+++ b/crates/syntax/src/fuzz.rs
@@ -1,4 +1,6 @@
-//! FIXME: write short doc here
+//! Some infrastructure for fuzzy testing.
+//!
+//! We don't normally run fuzzying, so this is hopelessly bitrotten :(
 
 use std::{
     convert::TryInto,
diff --git a/crates/syntax/src/parsing/text_tree_sink.rs b/crates/syntax/src/parsing/text_tree_sink.rs
index d63ec080b..25bfd41a1 100644
--- a/crates/syntax/src/parsing/text_tree_sink.rs
+++ b/crates/syntax/src/parsing/text_tree_sink.rs
@@ -1,4 +1,4 @@
-//! FIXME: write short doc here
+//! See [`TextTreeSink`].
 
 use std::mem;
 
diff --git a/crates/syntax/src/ptr.rs b/crates/syntax/src/ptr.rs
index d3fb7a5d9..195d2251b 100644
--- a/crates/syntax/src/ptr.rs
+++ b/crates/syntax/src/ptr.rs
@@ -1,4 +1,13 @@
-//! FIXME: write short doc here
+//! In rust-analyzer, syntax trees are transient objects.
+//!
+//! That means that we create trees when we need them, and tear them down to
+//! save memory. In this architecture, hanging on to a particular syntax node
+//! for a long time is ill-advisable, as that keeps the whole tree resident.
+//!
+//! Instead, we provide a [`SyntaxNodePtr`] type, which stores information about
+//! *location* of a particular syntax node in a tree. Its a small type which can
+//! be cheaply stored, and which can be resolved to a real [`SyntaxNode`] when
+//! necessary.
 
 use std::{
     hash::{Hash, Hasher},
diff --git a/crates/tt/src/buffer.rs b/crates/tt/src/buffer.rs
index 3606c887d..e0021039a 100644
--- a/crates/tt/src/buffer.rs
+++ b/crates/tt/src/buffer.rs
@@ -1,5 +1,6 @@
-//! FIXME: write short doc here
-
+//! Stateful iteration over token trees.
+//!
+//! We use this as the source of tokens for parser.
 use crate::{Leaf, Subtree, TokenTree};
 
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
@@ -104,7 +105,7 @@ impl<'t> TokenBuffer<'t> {
 
     /// Creates a cursor referencing the first token in the buffer and able to
     /// traverse until the end of the buffer.
-    pub fn begin(&self) -> Cursor {
+    pub fn begin(&self) -> Cursor<'_> {
         Cursor::create(self, EntryPtr(EntryId(0), 0))
     }
 
diff --git a/xtask/src/tidy.rs b/xtask/src/tidy.rs
index 6c55823eb..e31cc2a67 100644
--- a/xtask/src/tidy.rs
+++ b/xtask/src/tidy.rs
@@ -392,18 +392,7 @@ impl TidyDocs {
             )
         }
 
-        let poorly_documented = [
-            "hir",
-            "hir_expand",
-            "ide",
-            "mbe",
-            "parser",
-            "profile",
-            "project_model",
-            "syntax",
-            "tt",
-            "hir_ty",
-        ];
+        let poorly_documented = ["hir_expand", "mbe", "parser", "hir_ty"];
 
         let mut has_fixmes =
             poorly_documented.iter().map(|it| (*it, false)).collect::<HashMap<&str, bool>>();