170 files changed, 413 insertions, 29 deletions

diff --git a/crates/ra_assists/src/assist_ctx.rs b/crates/ra_assists/src/assist_ctx.rs
index 5f564be0b..189cad7d0 100644
--- a/crates/ra_assists/src/assist_ctx.rs
+++ b/crates/ra_assists/src/assist_ctx.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use hir::db::HirDatabase;
 use ra_db::FileRange;
 use ra_fmt::{leading_indent, reindent};
diff --git a/crates/ra_assists/src/assists/add_derive.rs b/crates/ra_assists/src/assists/add_derive.rs
index 8f2c6266e..77ecc33c9 100644
--- a/crates/ra_assists/src/assists/add_derive.rs
+++ b/crates/ra_assists/src/assists/add_derive.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use hir::db::HirDatabase;
 use ra_syntax::{
     ast::{self, AstNode, AttrsOwner},
diff --git a/crates/ra_assists/src/assists/add_explicit_type.rs b/crates/ra_assists/src/assists/add_explicit_type.rs
index 78f0f7f28..8c83dc987 100644
--- a/crates/ra_assists/src/assists/add_explicit_type.rs
+++ b/crates/ra_assists/src/assists/add_explicit_type.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use hir::{db::HirDatabase, HirDisplay, Ty};
 use ra_syntax::{
     ast::{self, AstNode, LetStmt, NameOwner},
diff --git a/crates/ra_assists/src/assists/add_impl.rs b/crates/ra_assists/src/assists/add_impl.rs
index 4b61f4031..94801fbc9 100644
--- a/crates/ra_assists/src/assists/add_impl.rs
+++ b/crates/ra_assists/src/assists/add_impl.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use format_buf::format;
 use hir::db::HirDatabase;
 use join_to_string::join;
diff --git a/crates/ra_assists/src/assists/add_missing_impl_members.rs b/crates/ra_assists/src/assists/add_missing_impl_members.rs
index 6fd1c3753..565b96fb5 100644
--- a/crates/ra_assists/src/assists/add_missing_impl_members.rs
+++ b/crates/ra_assists/src/assists/add_missing_impl_members.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use hir::{db::HirDatabase, HasSource};
 use ra_syntax::{
     ast::{self, edit, make, AstNode, NameOwner},
diff --git a/crates/ra_assists/src/assists/auto_import.rs b/crates/ra_assists/src/assists/auto_import.rs
index 419e93330..02c58e7c6 100644
--- a/crates/ra_assists/src/assists/auto_import.rs
+++ b/crates/ra_assists/src/assists/auto_import.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use hir::{self, db::HirDatabase};
 use ra_text_edit::TextEditBuilder;
 
diff --git a/crates/ra_assists/src/assists/change_visibility.rs b/crates/ra_assists/src/assists/change_visibility.rs
index 60c74debc..df92c6b67 100644
--- a/crates/ra_assists/src/assists/change_visibility.rs
+++ b/crates/ra_assists/src/assists/change_visibility.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use hir::db::HirDatabase;
 use ra_syntax::{
     ast::{self, NameOwner, VisibilityOwner},
diff --git a/crates/ra_assists/src/assists/fill_match_arms.rs b/crates/ra_assists/src/assists/fill_match_arms.rs
index db82db89a..7335cce09 100644
--- a/crates/ra_assists/src/assists/fill_match_arms.rs
+++ b/crates/ra_assists/src/assists/fill_match_arms.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::iter;
 
 use hir::{db::HirDatabase, Adt, HasSource};
diff --git a/crates/ra_assists/src/assists/flip_binexpr.rs b/crates/ra_assists/src/assists/flip_binexpr.rs
index b55b36a8e..c51035282 100644
--- a/crates/ra_assists/src/assists/flip_binexpr.rs
+++ b/crates/ra_assists/src/assists/flip_binexpr.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use hir::db::HirDatabase;
 use ra_syntax::ast::{AstNode, BinExpr, BinOp};
 
diff --git a/crates/ra_assists/src/assists/flip_comma.rs b/crates/ra_assists/src/assists/flip_comma.rs
index 5ee7561bc..e31cc5e7d 100644
--- a/crates/ra_assists/src/assists/flip_comma.rs
+++ b/crates/ra_assists/src/assists/flip_comma.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use hir::db::HirDatabase;
 use ra_syntax::{algo::non_trivia_sibling, Direction, T};
 
diff --git a/crates/ra_assists/src/assists/inline_local_variable.rs b/crates/ra_assists/src/assists/inline_local_variable.rs
index eedb29199..9bd64decc 100644
--- a/crates/ra_assists/src/assists/inline_local_variable.rs
+++ b/crates/ra_assists/src/assists/inline_local_variable.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use hir::db::HirDatabase;
 use ra_syntax::{
     ast::{self, AstNode, AstToken},
diff --git a/crates/ra_assists/src/assists/introduce_variable.rs b/crates/ra_assists/src/assists/introduce_variable.rs
index 470ffe120..43378c4b0 100644
--- a/crates/ra_assists/src/assists/introduce_variable.rs
+++ b/crates/ra_assists/src/assists/introduce_variable.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use format_buf::format;
 use hir::db::HirDatabase;
 use ra_syntax::{
diff --git a/crates/ra_assists/src/assists/merge_match_arms.rs b/crates/ra_assists/src/assists/merge_match_arms.rs
index 3b6a99895..17baa98f9 100644
--- a/crates/ra_assists/src/assists/merge_match_arms.rs
+++ b/crates/ra_assists/src/assists/merge_match_arms.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use crate::{Assist, AssistCtx, AssistId, TextRange, TextUnit};
 use hir::db::HirDatabase;
 use ra_syntax::ast::{AstNode, MatchArm};
diff --git a/crates/ra_assists/src/assists/move_bounds.rs b/crates/ra_assists/src/assists/move_bounds.rs
index 39ff51233..f791d22b0 100644
--- a/crates/ra_assists/src/assists/move_bounds.rs
+++ b/crates/ra_assists/src/assists/move_bounds.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use hir::db::HirDatabase;
 use ra_syntax::{
     ast::{self, edit, make, AstNode, NameOwner, TypeBoundsOwner},
diff --git a/crates/ra_assists/src/assists/move_guard.rs b/crates/ra_assists/src/assists/move_guard.rs
index 699221e33..51aea6334 100644
--- a/crates/ra_assists/src/assists/move_guard.rs
+++ b/crates/ra_assists/src/assists/move_guard.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use hir::db::HirDatabase;
 use ra_syntax::{
     ast,
diff --git a/crates/ra_assists/src/assists/raw_string.rs b/crates/ra_assists/src/assists/raw_string.rs
index 965a64c98..388ee7e97 100644
--- a/crates/ra_assists/src/assists/raw_string.rs
+++ b/crates/ra_assists/src/assists/raw_string.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use hir::db::HirDatabase;
 use ra_syntax::{ast::AstNode, ast::Literal, TextRange, TextUnit};
 
diff --git a/crates/ra_assists/src/assists/remove_dbg.rs b/crates/ra_assists/src/assists/remove_dbg.rs
index 870133fda..1a7e2b305 100644
--- a/crates/ra_assists/src/assists/remove_dbg.rs
+++ b/crates/ra_assists/src/assists/remove_dbg.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use crate::{Assist, AssistCtx, AssistId};
 use hir::db::HirDatabase;
 use ra_syntax::{
diff --git a/crates/ra_assists/src/assists/replace_if_let_with_match.rs b/crates/ra_assists/src/assists/replace_if_let_with_match.rs
index 401835c57..749ff338a 100644
--- a/crates/ra_assists/src/assists/replace_if_let_with_match.rs
+++ b/crates/ra_assists/src/assists/replace_if_let_with_match.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use format_buf::format;
 use hir::db::HirDatabase;
 use ra_fmt::extract_trivial_expression;
diff --git a/crates/ra_assists/src/assists/split_import.rs b/crates/ra_assists/src/assists/split_import.rs
index 2c1edddb9..19d429daf 100644
--- a/crates/ra_assists/src/assists/split_import.rs
+++ b/crates/ra_assists/src/assists/split_import.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::iter::successors;
 
 use hir::db::HirDatabase;
diff --git a/crates/ra_assists/src/marks.rs b/crates/ra_assists/src/marks.rs
index a29f9f658..c20e4db9e 100644
--- a/crates/ra_assists/src/marks.rs
+++ b/crates/ra_assists/src/marks.rs
@@ -1,3 +1,5 @@
+//! See test_utils/src/marks.rs
+
 test_utils::marks!(
     introduce_var_in_comment_is_not_applicable
     test_introduce_var_expr_stmt
diff --git a/crates/ra_batch/src/lib.rs b/crates/ra_batch/src/lib.rs
index ffc9e16bb..939f72037 100644
--- a/crates/ra_batch/src/lib.rs
+++ b/crates/ra_batch/src/lib.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::{collections::HashSet, error::Error, path::Path};
 
 use rustc_hash::FxHashMap;
diff --git a/crates/ra_cli/src/analysis_bench.rs b/crates/ra_cli/src/analysis_bench.rs
index 01b96ec58..727f1e62b 100644
--- a/crates/ra_cli/src/analysis_bench.rs
+++ b/crates/ra_cli/src/analysis_bench.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::{
     path::{Path, PathBuf},
     sync::Arc,
diff --git a/crates/ra_cli/src/analysis_stats.rs b/crates/ra_cli/src/analysis_stats.rs
index 6b1e44a2c..a8a110bd9 100644
--- a/crates/ra_cli/src/analysis_stats.rs
+++ b/crates/ra_cli/src/analysis_stats.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::{collections::HashSet, fmt::Write, path::Path, time::Instant};
 
 use ra_db::SourceDatabase;
diff --git a/crates/ra_cli/src/help.rs b/crates/ra_cli/src/help.rs
index 2a74b8733..d3c4c7d0b 100644
--- a/crates/ra_cli/src/help.rs
+++ b/crates/ra_cli/src/help.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 pub const GLOBAL_HELP: &str = "ra-cli
 
 USAGE:
diff --git a/crates/ra_cli/src/main.rs b/crates/ra_cli/src/main.rs
index 8b91ba3e9..e6c76087e 100644
--- a/crates/ra_cli/src/main.rs
+++ b/crates/ra_cli/src/main.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 mod analysis_stats;
 mod analysis_bench;
 mod help;
diff --git a/crates/ra_db/src/input.rs b/crates/ra_db/src/input.rs
index a1ace61b6..52f892891 100644
--- a/crates/ra_db/src/input.rs
+++ b/crates/ra_db/src/input.rs
@@ -1,10 +1,11 @@
-/// This module specifies the input to rust-analyzer. In some sense, this is
-/// **the** most important module, because all other fancy stuff is strictly
-/// derived from this input.
-///
-/// Note that neither this module, nor any other part of the analyzer's core do
-/// actual IO. See `vfs` and `project_model` in the `ra_lsp_server` crate for how
-/// actual IO is done and lowered to input.
+//! This module specifies the input to rust-analyzer. In some sense, this is
+//! **the** most important module, because all other fancy stuff is strictly
+//! derived from this input.
+//!
+//! Note that neither this module, nor any other part of the analyzer's core do
+//! actual IO. See `vfs` and `project_model` in the `ra_lsp_server` crate for how
+//! actual IO is done and lowered to input.
+
 use relative_path::{RelativePath, RelativePathBuf};
 use rustc_hash::FxHashMap;
 
diff --git a/crates/ra_hir/src/code_model.rs b/crates/ra_hir/src/code_model.rs
index fd7afcbb6..e3a7e8e3c 100644
--- a/crates/ra_hir/src/code_model.rs
+++ b/crates/ra_hir/src/code_model.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 pub(crate) mod src;
 pub(crate) mod docs;
 
diff --git a/crates/ra_hir/src/code_model/docs.rs b/crates/ra_hir/src/code_model/docs.rs
index 99edc5814..9675e397f 100644
--- a/crates/ra_hir/src/code_model/docs.rs
+++ b/crates/ra_hir/src/code_model/docs.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::sync::Arc;
 
 use ra_syntax::ast;
diff --git a/crates/ra_hir/src/code_model/src.rs b/crates/ra_hir/src/code_model/src.rs
index dc964e156..fdae26906 100644
--- a/crates/ra_hir/src/code_model/src.rs
+++ b/crates/ra_hir/src/code_model/src.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use ra_syntax::{
     ast::{self, AstNode},
     SyntaxNode,
diff --git a/crates/ra_hir/src/db.rs b/crates/ra_hir/src/db.rs
index deed1c62f..73d7d6fb6 100644
--- a/crates/ra_hir/src/db.rs
+++ b/crates/ra_hir/src/db.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::sync::Arc;
 
 use ra_db::{salsa, SourceDatabase};
diff --git a/crates/ra_hir/src/diagnostics.rs b/crates/ra_hir/src/diagnostics.rs
index 60da33695..9acdaf8ed 100644
--- a/crates/ra_hir/src/diagnostics.rs
+++ b/crates/ra_hir/src/diagnostics.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::{any::Any, fmt};
 
 use ra_syntax::{ast, AstNode, AstPtr, SyntaxNode, SyntaxNodePtr, TextRange};
diff --git a/crates/ra_hir/src/either.rs b/crates/ra_hir/src/either.rs
index 439e6ec87..83583ef8b 100644
--- a/crates/ra_hir/src/either.rs
+++ b/crates/ra_hir/src/either.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum Either<A, B> {
     A(A),
diff --git a/crates/ra_hir/src/expr.rs b/crates/ra_hir/src/expr.rs
index b1bec2a68..d238741ba 100644
--- a/crates/ra_hir/src/expr.rs
+++ b/crates/ra_hir/src/expr.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 pub(crate) mod lower;
 pub(crate) mod scope;
 pub(crate) mod validation;
diff --git a/crates/ra_hir/src/expr/lower.rs b/crates/ra_hir/src/expr/lower.rs
index 6d6f60506..50ea429ea 100644
--- a/crates/ra_hir/src/expr/lower.rs
+++ b/crates/ra_hir/src/expr/lower.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use ra_arena::Arena;
 use ra_syntax::{
     ast::{
diff --git a/crates/ra_hir/src/expr/scope.rs b/crates/ra_hir/src/expr/scope.rs
index de0983a7e..5496822e7 100644
--- a/crates/ra_hir/src/expr/scope.rs
+++ b/crates/ra_hir/src/expr/scope.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::sync::Arc;
 
 use ra_arena::{impl_arena_id, Arena, RawId};
diff --git a/crates/ra_hir/src/expr/validation.rs b/crates/ra_hir/src/expr/validation.rs
index f06e5ec07..1aa853c3e 100644
--- a/crates/ra_hir/src/expr/validation.rs
+++ b/crates/ra_hir/src/expr/validation.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::sync::Arc;
 
 use ra_syntax::ast;
diff --git a/crates/ra_hir/src/from_source.rs b/crates/ra_hir/src/from_source.rs
index 7b6d9b240..a012f33f7 100644
--- a/crates/ra_hir/src/from_source.rs
+++ b/crates/ra_hir/src/from_source.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use ra_db::{FileId, FilePosition};
 use ra_syntax::{
     algo::find_node_at_offset,
diff --git a/crates/ra_hir/src/ids.rs b/crates/ra_hir/src/ids.rs
index bcbcd3dd7..a3b65cc79 100644
--- a/crates/ra_hir/src/ids.rs
+++ b/crates/ra_hir/src/ids.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::{
     hash::{Hash, Hasher},
     sync::Arc,
diff --git a/crates/ra_hir/src/impl_block.rs b/crates/ra_hir/src/impl_block.rs
index c66a1c6a6..8cf74ddc7 100644
--- a/crates/ra_hir/src/impl_block.rs
+++ b/crates/ra_hir/src/impl_block.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use rustc_hash::FxHashMap;
 use std::sync::Arc;
 
diff --git a/crates/ra_hir/src/lang_item.rs b/crates/ra_hir/src/lang_item.rs
index dbba433fe..6c4e8ffbd 100644
--- a/crates/ra_hir/src/lang_item.rs
+++ b/crates/ra_hir/src/lang_item.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use rustc_hash::FxHashMap;
 use std::sync::Arc;
 
diff --git a/crates/ra_hir/src/lib.rs b/crates/ra_hir/src/lib.rs
index a9de9fb6b..00031deba 100644
--- a/crates/ra_hir/src/lib.rs
+++ b/crates/ra_hir/src/lib.rs
@@ -1,5 +1,3 @@
-#![recursion_limit = "512"]
-
 //! HIR (previously known as descriptors) provides a high-level object oriented
 //! access to Rust code.
 //!
@@ -7,6 +5,8 @@
 //! to a particular crate instance. That is, it has cfg flags and features
 //! applied. So, the relation between syntax and HIR is many-to-one.
 
+#![recursion_limit = "512"]
+
 macro_rules! impl_froms {
     ($e:ident: $($v:ident $(($($sv:ident),*))?),*) => {
         $(
diff --git a/crates/ra_hir/src/marks.rs b/crates/ra_hir/src/marks.rs
index 0fed46802..79af24b20 100644
--- a/crates/ra_hir/src/marks.rs
+++ b/crates/ra_hir/src/marks.rs
@@ -1,3 +1,5 @@
+//! See test_utils/src/marks.rs
+
 test_utils::marks!(
     bogus_paths
     name_res_works_for_broken_modules
diff --git a/crates/ra_hir/src/mock.rs b/crates/ra_hir/src/mock.rs
index cb405091e..50feb98fb 100644
--- a/crates/ra_hir/src/mock.rs
+++ b/crates/ra_hir/src/mock.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::{panic, sync::Arc};
 
 use parking_lot::Mutex;
diff --git a/crates/ra_hir/src/name.rs b/crates/ra_hir/src/name.rs
index d50867f5d..1e0b8c350 100644
--- a/crates/ra_hir/src/name.rs
+++ b/crates/ra_hir/src/name.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::fmt;
 
 use ra_syntax::{ast, SmolStr};
diff --git a/crates/ra_hir/src/nameres/collector.rs b/crates/ra_hir/src/nameres/collector.rs
index 65929c522..a568fdabd 100644
--- a/crates/ra_hir/src/nameres/collector.rs
+++ b/crates/ra_hir/src/nameres/collector.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use ra_db::FileId;
 use ra_syntax::{ast, SmolStr};
 use rustc_hash::FxHashMap;
diff --git a/crates/ra_hir/src/nameres/per_ns.rs b/crates/ra_hir/src/nameres/per_ns.rs
index 964da2794..0da6789de 100644
--- a/crates/ra_hir/src/nameres/per_ns.rs
+++ b/crates/ra_hir/src/nameres/per_ns.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use crate::{MacroDef, ModuleDef};
 
 #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
diff --git a/crates/ra_hir/src/nameres/raw.rs b/crates/ra_hir/src/nameres/raw.rs
index 0e27dd2db..606bd1a95 100644
--- a/crates/ra_hir/src/nameres/raw.rs
+++ b/crates/ra_hir/src/nameres/raw.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::{ops::Index, sync::Arc};
 
 use ra_arena::{impl_arena_id, map::ArenaMap, Arena, RawId};
diff --git a/crates/ra_hir/src/path.rs b/crates/ra_hir/src/path.rs
index 158c853d4..394617e1a 100644
--- a/crates/ra_hir/src/path.rs
+++ b/crates/ra_hir/src/path.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::{iter, sync::Arc};
 
 use ra_syntax::{
diff --git a/crates/ra_hir/src/source_binder.rs b/crates/ra_hir/src/source_binder.rs
index 6e89bfc76..088335e66 100644
--- a/crates/ra_hir/src/source_binder.rs
+++ b/crates/ra_hir/src/source_binder.rs
@@ -1,10 +1,10 @@
-/// Lookup hir elements using positions in the source code. This is a lossy
-/// transformation: in general, a single source might correspond to several
-/// modules, functions, etc, due to macros, cfgs and `#[path=]` attributes on
-/// modules.
-///
-/// So, this modules should not be used during hir construction, it exists
-/// purely for "IDE needs".
+//! Lookup hir elements using positions in the source code. This is a lossy
+//! transformation: in general, a single source might correspond to several
+//! modules, functions, etc, due to macros, cfgs and `#[path=]` attributes on
+//! modules.
+//!
+//! So, this modules should not be used during hir construction, it exists
+//! purely for "IDE needs".
 use std::sync::Arc;
 
 use ra_db::FileId;
diff --git a/crates/ra_hir/src/source_id.rs b/crates/ra_hir/src/source_id.rs
index 04574876d..a4dd99598 100644
--- a/crates/ra_hir/src/source_id.rs
+++ b/crates/ra_hir/src/source_id.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::{
     hash::{Hash, Hasher},
     marker::PhantomData,
diff --git a/crates/ra_hir/src/ty/display.rs b/crates/ra_hir/src/ty/display.rs
index 63ec9d7e1..7910429d7 100644
--- a/crates/ra_hir/src/ty/display.rs
+++ b/crates/ra_hir/src/ty/display.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::fmt;
 
 use crate::db::HirDatabase;
diff --git a/crates/ra_hir/src/ty/op.rs b/crates/ra_hir/src/ty/op.rs
index 1b30a5b9b..bcfa3a6a2 100644
--- a/crates/ra_hir/src/ty/op.rs
+++ b/crates/ra_hir/src/ty/op.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use super::{InferTy, Ty, TypeCtor};
 use crate::{
     expr::{BinaryOp, CmpOp},
diff --git a/crates/ra_hir/src/ty/primitive.rs b/crates/ra_hir/src/ty/primitive.rs
index 2c60fefd6..8966f9d1d 100644
--- a/crates/ra_hir/src/ty/primitive.rs
+++ b/crates/ra_hir/src/ty/primitive.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::fmt;
 
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
diff --git a/crates/ra_ide_api/src/assists.rs b/crates/ra_ide_api/src/assists.rs
index e3d1ac529..e00589733 100644
--- a/crates/ra_ide_api/src/assists.rs
+++ b/crates/ra_ide_api/src/assists.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use ra_db::{FilePosition, FileRange};
 
 use crate::{db::RootDatabase, SourceChange, SourceFileEdit};
diff --git a/crates/ra_ide_api/src/call_info.rs b/crates/ra_ide_api/src/call_info.rs
index d5e116526..7d18be483 100644
--- a/crates/ra_ide_api/src/call_info.rs
+++ b/crates/ra_ide_api/src/call_info.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use ra_db::SourceDatabase;
 use ra_syntax::{
     algo::find_node_at_offset,
diff --git a/crates/ra_ide_api/src/change.rs b/crates/ra_ide_api/src/change.rs
index 981851829..09913787b 100644
--- a/crates/ra_ide_api/src/change.rs
+++ b/crates/ra_ide_api/src/change.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::{fmt, sync::Arc, time};
 
 use ra_db::{
diff --git a/crates/ra_ide_api/src/completion.rs b/crates/ra_ide_api/src/completion.rs
index 0ad414831..abe1f36ce 100644
--- a/crates/ra_ide_api/src/completion.rs
+++ b/crates/ra_ide_api/src/completion.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 mod completion_item;
 mod completion_context;
 mod presentation;
diff --git a/crates/ra_ide_api/src/completion/complete_dot.rs b/crates/ra_ide_api/src/completion/complete_dot.rs
index 9e64c8659..28c8324d0 100644
--- a/crates/ra_ide_api/src/completion/complete_dot.rs
+++ b/crates/ra_ide_api/src/completion/complete_dot.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use hir::{Adt, Ty, TypeCtor};
 
 use crate::completion::completion_item::CompletionKind;
diff --git a/crates/ra_ide_api/src/completion/complete_fn_param.rs b/crates/ra_ide_api/src/completion/complete_fn_param.rs
index 6639b6fff..844a63f6c 100644
--- a/crates/ra_ide_api/src/completion/complete_fn_param.rs
+++ b/crates/ra_ide_api/src/completion/complete_fn_param.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use ra_syntax::{
     algo::visit::{visitor_ctx, VisitorCtx},
     ast, AstNode,
diff --git a/crates/ra_ide_api/src/completion/complete_keyword.rs b/crates/ra_ide_api/src/completion/complete_keyword.rs
index c527a9f63..3f121d45c 100644
--- a/crates/ra_ide_api/src/completion/complete_keyword.rs
+++ b/crates/ra_ide_api/src/completion/complete_keyword.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use ra_syntax::{
     algo::visit::{visitor, Visitor},
     ast::{self, LoopBodyOwner},
diff --git a/crates/ra_ide_api/src/completion/complete_macro_in_item_position.rs b/crates/ra_ide_api/src/completion/complete_macro_in_item_position.rs
index 0cbe4abf7..d808b2357 100644
--- a/crates/ra_ide_api/src/completion/complete_macro_in_item_position.rs
+++ b/crates/ra_ide_api/src/completion/complete_macro_in_item_position.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use crate::completion::{CompletionContext, Completions};
 
 pub(super) fn complete_macro_in_item_position(acc: &mut Completions, ctx: &CompletionContext) {
diff --git a/crates/ra_ide_api/src/completion/complete_path.rs b/crates/ra_ide_api/src/completion/complete_path.rs
index e9fec54d8..e01197fe4 100644
--- a/crates/ra_ide_api/src/completion/complete_path.rs
+++ b/crates/ra_ide_api/src/completion/complete_path.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use hir::{Adt, Either, PathResolution};
 use ra_syntax::AstNode;
 use test_utils::tested_by;
diff --git a/crates/ra_ide_api/src/completion/complete_pattern.rs b/crates/ra_ide_api/src/completion/complete_pattern.rs
index c17b5b7ee..513ad6e5f 100644
--- a/crates/ra_ide_api/src/completion/complete_pattern.rs
+++ b/crates/ra_ide_api/src/completion/complete_pattern.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use crate::completion::{CompletionContext, Completions};
 
 /// Completes constats and paths in patterns.
diff --git a/crates/ra_ide_api/src/completion/complete_postfix.rs b/crates/ra_ide_api/src/completion/complete_postfix.rs
index 3970d1af3..445a02676 100644
--- a/crates/ra_ide_api/src/completion/complete_postfix.rs
+++ b/crates/ra_ide_api/src/completion/complete_postfix.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use crate::{
     completion::{
         completion_context::CompletionContext,
diff --git a/crates/ra_ide_api/src/completion/complete_record_literal.rs b/crates/ra_ide_api/src/completion/complete_record_literal.rs
index ed4029964..4406695d5 100644
--- a/crates/ra_ide_api/src/completion/complete_record_literal.rs
+++ b/crates/ra_ide_api/src/completion/complete_record_literal.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use hir::Substs;
 
 use crate::completion::{CompletionContext, Completions};
diff --git a/crates/ra_ide_api/src/completion/complete_record_pattern.rs b/crates/ra_ide_api/src/completion/complete_record_pattern.rs
index 70716b3d6..d20fa796c 100644
--- a/crates/ra_ide_api/src/completion/complete_record_pattern.rs
+++ b/crates/ra_ide_api/src/completion/complete_record_pattern.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use hir::Substs;
 
 use crate::completion::{CompletionContext, Completions};
diff --git a/crates/ra_ide_api/src/completion/complete_scope.rs b/crates/ra_ide_api/src/completion/complete_scope.rs
index cb70a1f21..515a6285c 100644
--- a/crates/ra_ide_api/src/completion/complete_scope.rs
+++ b/crates/ra_ide_api/src/completion/complete_scope.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use ra_assists::auto_import_text_edit;
 use ra_syntax::{ast, AstNode, SmolStr};
 use ra_text_edit::TextEditBuilder;
diff --git a/crates/ra_ide_api/src/completion/complete_snippet.rs b/crates/ra_ide_api/src/completion/complete_snippet.rs
index b06221c2a..2df79b6c3 100644
--- a/crates/ra_ide_api/src/completion/complete_snippet.rs
+++ b/crates/ra_ide_api/src/completion/complete_snippet.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use crate::completion::{
     completion_item::Builder, CompletionContext, CompletionItem, CompletionItemKind,
     CompletionKind, Completions,
diff --git a/crates/ra_ide_api/src/completion/completion_context.rs b/crates/ra_ide_api/src/completion/completion_context.rs
index 57542152f..e9ad06965 100644
--- a/crates/ra_ide_api/src/completion/completion_context.rs
+++ b/crates/ra_ide_api/src/completion/completion_context.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use ra_syntax::{
     algo::{find_covering_element, find_node_at_offset},
     ast, AstNode, Parse, SourceFile,
diff --git a/crates/ra_ide_api/src/completion/completion_item.rs b/crates/ra_ide_api/src/completion/completion_item.rs
index d787bb69e..b1f0390ec 100644
--- a/crates/ra_ide_api/src/completion/completion_item.rs
+++ b/crates/ra_ide_api/src/completion/completion_item.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::fmt;
 
 use hir::Documentation;
diff --git a/crates/ra_ide_api/src/completion/presentation.rs b/crates/ra_ide_api/src/completion/presentation.rs
index b8aa433c1..48028a2f9 100644
--- a/crates/ra_ide_api/src/completion/presentation.rs
+++ b/crates/ra_ide_api/src/completion/presentation.rs
@@ -1,4 +1,5 @@
 //! This modules takes care of rendering various definitions as completion items.
+
 use hir::{Docs, HasSource, HirDisplay, ScopeDef, Ty, TypeWalk};
 use join_to_string::join;
 use ra_syntax::ast::NameOwner;
diff --git a/crates/ra_ide_api/src/db.rs b/crates/ra_ide_api/src/db.rs
index afd9022ce..ea0714add 100644
--- a/crates/ra_ide_api/src/db.rs
+++ b/crates/ra_ide_api/src/db.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::sync::Arc;
 
 use ra_db::{
diff --git a/crates/ra_ide_api/src/diagnostics.rs b/crates/ra_ide_api/src/diagnostics.rs
index 4fa07e3dc..0435188c8 100644
--- a/crates/ra_ide_api/src/diagnostics.rs
+++ b/crates/ra_ide_api/src/diagnostics.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::cell::RefCell;
 
 use hir::diagnostics::{AstDiagnostic, Diagnostic as _, DiagnosticSink};
diff --git a/crates/ra_ide_api/src/display/function_signature.rs b/crates/ra_ide_api/src/display/function_signature.rs
index 644a4532b..43f022ccd 100644
--- a/crates/ra_ide_api/src/display/function_signature.rs
+++ b/crates/ra_ide_api/src/display/function_signature.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::fmt::{self, Display};
 
 use hir::{Docs, Documentation, HasSource};
diff --git a/crates/ra_ide_api/src/display/navigation_target.rs b/crates/ra_ide_api/src/display/navigation_target.rs
index d3e774bd0..60ae802c0 100644
--- a/crates/ra_ide_api/src/display/navigation_target.rs
+++ b/crates/ra_ide_api/src/display/navigation_target.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use hir::{AssocItem, FieldSource, HasSource, ModuleSource};
 use ra_db::{FileId, SourceDatabase};
 use ra_syntax::{
diff --git a/crates/ra_ide_api/src/display/short_label.rs b/crates/ra_ide_api/src/display/short_label.rs
index b16d504e1..5d2bce3d2 100644
--- a/crates/ra_ide_api/src/display/short_label.rs
+++ b/crates/ra_ide_api/src/display/short_label.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use format_buf::format;
 use ra_syntax::ast::{self, AstNode, NameOwner, TypeAscriptionOwner, VisibilityOwner};
 
diff --git a/crates/ra_ide_api/src/display/structure.rs b/crates/ra_ide_api/src/display/structure.rs
index 38a56d752..8815df747 100644
--- a/crates/ra_ide_api/src/display/structure.rs
+++ b/crates/ra_ide_api/src/display/structure.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use crate::TextRange;
 
 use ra_syntax::{
diff --git a/crates/ra_ide_api/src/extend_selection.rs b/crates/ra_ide_api/src/extend_selection.rs
index e990eb0d1..33fefb541 100644
--- a/crates/ra_ide_api/src/extend_selection.rs
+++ b/crates/ra_ide_api/src/extend_selection.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use ra_db::SourceDatabase;
 use ra_syntax::{
     algo::find_covering_element,
diff --git a/crates/ra_ide_api/src/feature_flags.rs b/crates/ra_ide_api/src/feature_flags.rs
index 9f82ac71c..d3ca7be03 100644
--- a/crates/ra_ide_api/src/feature_flags.rs
+++ b/crates/ra_ide_api/src/feature_flags.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use rustc_hash::FxHashMap;
 
 /// Feature flags hold fine-grained toggles for all *user-visible* features of
diff --git a/crates/ra_ide_api/src/folding_ranges.rs b/crates/ra_ide_api/src/folding_ranges.rs
index 79fadcc5d..4eeb76d14 100644
--- a/crates/ra_ide_api/src/folding_ranges.rs
+++ b/crates/ra_ide_api/src/folding_ranges.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use rustc_hash::FxHashSet;
 
 use ra_syntax::{
diff --git a/crates/ra_ide_api/src/goto_definition.rs b/crates/ra_ide_api/src/goto_definition.rs
index bc8863dad..567d4a674 100644
--- a/crates/ra_ide_api/src/goto_definition.rs
+++ b/crates/ra_ide_api/src/goto_definition.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use ra_db::{FileId, SourceDatabase};
 use ra_syntax::{
     algo::{
diff --git a/crates/ra_ide_api/src/goto_type_definition.rs b/crates/ra_ide_api/src/goto_type_definition.rs
index 72884e5ca..059d80524 100644
--- a/crates/ra_ide_api/src/goto_type_definition.rs
+++ b/crates/ra_ide_api/src/goto_type_definition.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use ra_db::SourceDatabase;
 use ra_syntax::{ast, AstNode};
 
diff --git a/crates/ra_ide_api/src/hover.rs b/crates/ra_ide_api/src/hover.rs
index 655bcdb16..200b57679 100644
--- a/crates/ra_ide_api/src/hover.rs
+++ b/crates/ra_ide_api/src/hover.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use hir::{Adt, HasSource, HirDisplay};
 use ra_db::SourceDatabase;
 use ra_syntax::{
diff --git a/crates/ra_ide_api/src/impls.rs b/crates/ra_ide_api/src/impls.rs
index f57f9a21b..7fc1b1efa 100644
--- a/crates/ra_ide_api/src/impls.rs
+++ b/crates/ra_ide_api/src/impls.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use hir::{db::HirDatabase, ApplicationTy, FromSource, Ty, TypeCtor};
 use ra_db::SourceDatabase;
 use ra_syntax::{algo::find_node_at_offset, ast, AstNode};
diff --git a/crates/ra_ide_api/src/inlay_hints.rs b/crates/ra_ide_api/src/inlay_hints.rs
index 16bdcf9d1..9b45575f8 100644
--- a/crates/ra_ide_api/src/inlay_hints.rs
+++ b/crates/ra_ide_api/src/inlay_hints.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use crate::{db::RootDatabase, FileId};
 use hir::{HirDisplay, SourceAnalyzer, Ty};
 use ra_syntax::{
diff --git a/crates/ra_ide_api/src/join_lines.rs b/crates/ra_ide_api/src/join_lines.rs
index a71e4ed7d..6f71b27db 100644
--- a/crates/ra_ide_api/src/join_lines.rs
+++ b/crates/ra_ide_api/src/join_lines.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use itertools::Itertools;
 use ra_fmt::{compute_ws, extract_trivial_expression};
 use ra_syntax::{
diff --git a/crates/ra_ide_api/src/line_index.rs b/crates/ra_ide_api/src/line_index.rs
index 5fedad696..710890d27 100644
--- a/crates/ra_ide_api/src/line_index.rs
+++ b/crates/ra_ide_api/src/line_index.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use crate::TextUnit;
 use rustc_hash::FxHashMap;
 use superslice::Ext;
diff --git a/crates/ra_ide_api/src/line_index_utils.rs b/crates/ra_ide_api/src/line_index_utils.rs
index 534009b98..bd1e08feb 100644
--- a/crates/ra_ide_api/src/line_index_utils.rs
+++ b/crates/ra_ide_api/src/line_index_utils.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use crate::{line_index::Utf16Char, LineCol, LineIndex};
 use ra_syntax::{TextRange, TextUnit};
 use ra_text_edit::{AtomTextEdit, TextEdit};
diff --git a/crates/ra_ide_api/src/marks.rs b/crates/ra_ide_api/src/marks.rs
index c3752cc54..3f4ba248b 100644
--- a/crates/ra_ide_api/src/marks.rs
+++ b/crates/ra_ide_api/src/marks.rs
@@ -1,3 +1,5 @@
+//! See test_utils/src/marks.rs
+
 test_utils::marks!(
     inserts_parens_for_function_calls
     goto_definition_works_for_macros
diff --git a/crates/ra_ide_api/src/matching_brace.rs b/crates/ra_ide_api/src/matching_brace.rs
index e802d01e4..d1204fac0 100644
--- a/crates/ra_ide_api/src/matching_brace.rs
+++ b/crates/ra_ide_api/src/matching_brace.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use ra_syntax::{ast::AstNode, SourceFile, SyntaxKind, TextUnit, T};
 
 pub fn matching_brace(file: &SourceFile, offset: TextUnit) -> Option<TextUnit> {
diff --git a/crates/ra_ide_api/src/mock_analysis.rs b/crates/ra_ide_api/src/mock_analysis.rs
index 132f6f875..16870c7ae 100644
--- a/crates/ra_ide_api/src/mock_analysis.rs
+++ b/crates/ra_ide_api/src/mock_analysis.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::sync::Arc;
 
 use relative_path::RelativePathBuf;
diff --git a/crates/ra_ide_api/src/name_ref_kind.rs b/crates/ra_ide_api/src/name_ref_kind.rs
index aff03464a..149585971 100644
--- a/crates/ra_ide_api/src/name_ref_kind.rs
+++ b/crates/ra_ide_api/src/name_ref_kind.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use hir::Either;
 use ra_syntax::{ast, AstNode, AstPtr};
 use test_utils::tested_by;
diff --git a/crates/ra_ide_api/src/parent_module.rs b/crates/ra_ide_api/src/parent_module.rs
index 3668da8d7..c85f1d0d0 100644
--- a/crates/ra_ide_api/src/parent_module.rs
+++ b/crates/ra_ide_api/src/parent_module.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use ra_db::{CrateId, FileId, FilePosition};
 
 use crate::{db::RootDatabase, NavigationTarget};
diff --git a/crates/ra_ide_api/src/references.rs b/crates/ra_ide_api/src/references.rs
index acca71f2a..84c2eb793 100644
--- a/crates/ra_ide_api/src/references.rs
+++ b/crates/ra_ide_api/src/references.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use hir::{Either, ModuleSource};
 use ra_db::SourceDatabase;
 use ra_syntax::{algo::find_node_at_offset, ast, AstNode, SourceFile, SyntaxNode};
diff --git a/crates/ra_ide_api/src/runnables.rs b/crates/ra_ide_api/src/runnables.rs
index 8cf58fe79..910883da7 100644
--- a/crates/ra_ide_api/src/runnables.rs
+++ b/crates/ra_ide_api/src/runnables.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use itertools::Itertools;
 use ra_db::SourceDatabase;
 use ra_syntax::{
diff --git a/crates/ra_ide_api/src/status.rs b/crates/ra_ide_api/src/status.rs
index dee2ea46a..f91f16c8e 100644
--- a/crates/ra_ide_api/src/status.rs
+++ b/crates/ra_ide_api/src/status.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::{fmt, iter::FromIterator, sync::Arc};
 
 use hir::MacroFile;
diff --git a/crates/ra_ide_api/src/syntax_highlighting.rs b/crates/ra_ide_api/src/syntax_highlighting.rs
index 3d7f91c1d..9ae2dc061 100644
--- a/crates/ra_ide_api/src/syntax_highlighting.rs
+++ b/crates/ra_ide_api/src/syntax_highlighting.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use rustc_hash::{FxHashMap, FxHashSet};
 
 use hir::{Mutability, Ty};
diff --git a/crates/ra_ide_api/src/syntax_tree.rs b/crates/ra_ide_api/src/syntax_tree.rs
index e2bb120b4..4d0f0fc47 100644
--- a/crates/ra_ide_api/src/syntax_tree.rs
+++ b/crates/ra_ide_api/src/syntax_tree.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use crate::db::RootDatabase;
 use ra_db::SourceDatabase;
 use ra_syntax::{
diff --git a/crates/ra_ide_api/src/test_utils.rs b/crates/ra_ide_api/src/test_utils.rs
index 6e0d883b4..8adb214d4 100644
--- a/crates/ra_ide_api/src/test_utils.rs
+++ b/crates/ra_ide_api/src/test_utils.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use ra_syntax::{SourceFile, TextUnit};
 use ra_text_edit::TextEdit;
 
diff --git a/crates/ra_ide_api/src/typing.rs b/crates/ra_ide_api/src/typing.rs
index 2d4491442..2f5782012 100644
--- a/crates/ra_ide_api/src/typing.rs
+++ b/crates/ra_ide_api/src/typing.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use ra_db::{FilePosition, SourceDatabase};
 use ra_fmt::leading_indent;
 use ra_syntax::{
diff --git a/crates/ra_ide_api/src/wasm_shims.rs b/crates/ra_ide_api/src/wasm_shims.rs
index 592dddf44..088cc9be4 100644
--- a/crates/ra_ide_api/src/wasm_shims.rs
+++ b/crates/ra_ide_api/src/wasm_shims.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 #[cfg(not(feature = "wasm"))]
 pub use std::time::Instant;
 
diff --git a/crates/ra_lsp_server/src/caps.rs b/crates/ra_lsp_server/src/caps.rs
index 22fc97a97..30bcbd7a8 100644
--- a/crates/ra_lsp_server/src/caps.rs
+++ b/crates/ra_lsp_server/src/caps.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use lsp_types::{
     CodeActionProviderCapability, CodeLensOptions, CompletionOptions,
     DocumentOnTypeFormattingOptions, FoldingRangeProviderCapability, GenericCapability,
diff --git a/crates/ra_lsp_server/src/cargo_target_spec.rs b/crates/ra_lsp_server/src/cargo_target_spec.rs
index a083bb311..d996b53de 100644
--- a/crates/ra_lsp_server/src/cargo_target_spec.rs
+++ b/crates/ra_lsp_server/src/cargo_target_spec.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use ra_ide_api::{FileId, RunnableKind};
 use ra_project_model::{self, ProjectWorkspace, TargetKind};
 
diff --git a/crates/ra_lsp_server/src/config.rs b/crates/ra_lsp_server/src/config.rs
index cf53e7c4c..579d4c692 100644
--- a/crates/ra_lsp_server/src/config.rs
+++ b/crates/ra_lsp_server/src/config.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use rustc_hash::FxHashMap;
 
 use serde::{Deserialize, Deserializer};
diff --git a/crates/ra_lsp_server/src/conv.rs b/crates/ra_lsp_server/src/conv.rs
index d78f77925..1318a1738 100644
--- a/crates/ra_lsp_server/src/conv.rs
+++ b/crates/ra_lsp_server/src/conv.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use lsp_types::{
     self, CreateFile, DiagnosticSeverity, DocumentChangeOperation, DocumentChanges, Documentation,
     Location, LocationLink, MarkupContent, MarkupKind, Position, Range, RenameFile, ResourceOp,
diff --git a/crates/ra_lsp_server/src/lib.rs b/crates/ra_lsp_server/src/lib.rs
index fa3d88abd..7a71a90fb 100644
--- a/crates/ra_lsp_server/src/lib.rs
+++ b/crates/ra_lsp_server/src/lib.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 #![recursion_limit = "512"]
 mod caps;
 mod cargo_target_spec;
diff --git a/crates/ra_lsp_server/src/main.rs b/crates/ra_lsp_server/src/main.rs
index 852fae027..7d9a1d054 100644
--- a/crates/ra_lsp_server/src/main.rs
+++ b/crates/ra_lsp_server/src/main.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use flexi_logger::{Duplicate, Logger};
 use lsp_server::Connection;
 
diff --git a/crates/ra_lsp_server/src/main_loop.rs b/crates/ra_lsp_server/src/main_loop.rs
index 2059f9800..35c35d32b 100644
--- a/crates/ra_lsp_server/src/main_loop.rs
+++ b/crates/ra_lsp_server/src/main_loop.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 mod handlers;
 mod subscriptions;
 pub(crate) mod pending_requests;
diff --git a/crates/ra_lsp_server/src/main_loop/handlers.rs b/crates/ra_lsp_server/src/main_loop/handlers.rs
index ae57e57e9..10e271376 100644
--- a/crates/ra_lsp_server/src/main_loop/handlers.rs
+++ b/crates/ra_lsp_server/src/main_loop/handlers.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::{fmt::Write as _, io::Write as _};
 
 use lsp_server::ErrorCode;
diff --git a/crates/ra_lsp_server/src/main_loop/pending_requests.rs b/crates/ra_lsp_server/src/main_loop/pending_requests.rs
index 7a99fc679..e7ea7aa5b 100644
--- a/crates/ra_lsp_server/src/main_loop/pending_requests.rs
+++ b/crates/ra_lsp_server/src/main_loop/pending_requests.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::time::{Duration, Instant};
 
 use lsp_server::RequestId;
diff --git a/crates/ra_lsp_server/src/main_loop/subscriptions.rs b/crates/ra_lsp_server/src/main_loop/subscriptions.rs
index bbeda723c..3856263b0 100644
--- a/crates/ra_lsp_server/src/main_loop/subscriptions.rs
+++ b/crates/ra_lsp_server/src/main_loop/subscriptions.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use ra_ide_api::FileId;
 use rustc_hash::FxHashSet;
 
diff --git a/crates/ra_lsp_server/src/markdown.rs b/crates/ra_lsp_server/src/markdown.rs
index 3659edf8e..f51fc4ade 100644
--- a/crates/ra_lsp_server/src/markdown.rs
+++ b/crates/ra_lsp_server/src/markdown.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 pub(crate) fn format_docs(src: &str) -> String {
     let mut processed_lines = Vec::new();
     let mut in_code_block = false;
diff --git a/crates/ra_lsp_server/src/req.rs b/crates/ra_lsp_server/src/req.rs
index 0540f166e..d25fc5726 100644
--- a/crates/ra_lsp_server/src/req.rs
+++ b/crates/ra_lsp_server/src/req.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use lsp_types::{Location, Position, Range, TextDocumentIdentifier, Url};
 use rustc_hash::FxHashMap;
 use serde::{Deserialize, Serialize};
diff --git a/crates/ra_lsp_server/src/world.rs b/crates/ra_lsp_server/src/world.rs
index 232409c3b..b55046ec9 100644
--- a/crates/ra_lsp_server/src/world.rs
+++ b/crates/ra_lsp_server/src/world.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::{
     path::{Path, PathBuf},
     sync::Arc,
diff --git a/crates/ra_mbe/src/lib.rs b/crates/ra_mbe/src/lib.rs
index a0904323c..afdbee84e 100644
--- a/crates/ra_mbe/src/lib.rs
+++ b/crates/ra_mbe/src/lib.rs
@@ -1,7 +1,7 @@
-/// `mbe` (short for Macro By Example) crate contains code for handling
-/// `macro_rules` macros. It uses `TokenTree` (from `ra_tt` package) as the
-/// interface, although it contains some code to bridge `SyntaxNode`s and
-/// `TokenTree`s as well!
+//! `mbe` (short for Macro By Example) crate contains code for handling
+//! `macro_rules` macros. It uses `TokenTree` (from `ra_tt` package) as the
+//! interface, although it contains some code to bridge `SyntaxNode`s and
+//! `TokenTree`s as well!
 
 mod parser;
 mod mbe_expander;
diff --git a/crates/ra_mbe/src/mbe_expander/matcher.rs b/crates/ra_mbe/src/mbe_expander/matcher.rs
index aff953102..0548e8512 100644
--- a/crates/ra_mbe/src/mbe_expander/matcher.rs
+++ b/crates/ra_mbe/src/mbe_expander/matcher.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use crate::{
     mbe_expander::{Binding, Bindings, Fragment},
     parser::{parse_pattern, Op, RepeatKind, Separator},
diff --git a/crates/ra_mbe/src/subtree_source.rs b/crates/ra_mbe/src/subtree_source.rs
index cf7458905..7ef45f6dc 100644
--- a/crates/ra_mbe/src/subtree_source.rs
+++ b/crates/ra_mbe/src/subtree_source.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use ra_parser::{Token, TokenSource};
 use ra_syntax::{classify_literal, SmolStr, SyntaxKind, SyntaxKind::*, T};
 use std::cell::{Cell, Ref, RefCell};
diff --git a/crates/ra_mbe/src/syntax_bridge.rs b/crates/ra_mbe/src/syntax_bridge.rs
index 2d035307b..1b543c84b 100644
--- a/crates/ra_mbe/src/syntax_bridge.rs
+++ b/crates/ra_mbe/src/syntax_bridge.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use ra_parser::{
     FragmentKind::{self, *},
     ParseError, TreeSink,
diff --git a/crates/ra_mbe/src/tt_iter.rs b/crates/ra_mbe/src/tt_iter.rs
index c53f99d1e..319f1ee65 100644
--- a/crates/ra_mbe/src/tt_iter.rs
+++ b/crates/ra_mbe/src/tt_iter.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 #[derive(Debug, Clone)]
 pub(crate) struct TtIter<'a> {
     pub(crate) inner: std::slice::Iter<'a, tt::TokenTree>,
diff --git a/crates/ra_parser/src/grammar/attributes.rs b/crates/ra_parser/src/grammar/attributes.rs
index 63ca9ca32..f3158ade3 100644
--- a/crates/ra_parser/src/grammar/attributes.rs
+++ b/crates/ra_parser/src/grammar/attributes.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use super::*;
 
 pub(super) fn inner_attributes(p: &mut Parser) {
diff --git a/crates/ra_parser/src/grammar/expressions.rs b/crates/ra_parser/src/grammar/expressions.rs
index 80b085280..413ecb278 100644
--- a/crates/ra_parser/src/grammar/expressions.rs
+++ b/crates/ra_parser/src/grammar/expressions.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 mod atom;
 
 pub(crate) use self::atom::match_arm_list;
diff --git a/crates/ra_parser/src/grammar/expressions/atom.rs b/crates/ra_parser/src/grammar/expressions/atom.rs
index 457f42a26..a52bdb3ea 100644
--- a/crates/ra_parser/src/grammar/expressions/atom.rs
+++ b/crates/ra_parser/src/grammar/expressions/atom.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use super::*;
 
 // test expr_literals
diff --git a/crates/ra_parser/src/grammar/items.rs b/crates/ra_parser/src/grammar/items.rs
index 4c67a5c2e..85f7eeb00 100644
--- a/crates/ra_parser/src/grammar/items.rs
+++ b/crates/ra_parser/src/grammar/items.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 mod consts;
 mod nominal;
 mod traits;
diff --git a/crates/ra_parser/src/grammar/items/consts.rs b/crates/ra_parser/src/grammar/items/consts.rs
index 310260689..742a7e056 100644
--- a/crates/ra_parser/src/grammar/items/consts.rs
+++ b/crates/ra_parser/src/grammar/items/consts.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use super::*;
 
 pub(super) fn static_def(p: &mut Parser, m: Marker) {
diff --git a/crates/ra_parser/src/grammar/items/nominal.rs b/crates/ra_parser/src/grammar/items/nominal.rs
index bede3b692..9d8fb8486 100644
--- a/crates/ra_parser/src/grammar/items/nominal.rs
+++ b/crates/ra_parser/src/grammar/items/nominal.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use super::*;
 
 pub(super) fn struct_def(p: &mut Parser, m: Marker, kind: SyntaxKind) {
diff --git a/crates/ra_parser/src/grammar/items/traits.rs b/crates/ra_parser/src/grammar/items/traits.rs
index 3742fd197..2c560e824 100644
--- a/crates/ra_parser/src/grammar/items/traits.rs
+++ b/crates/ra_parser/src/grammar/items/traits.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use super::*;
 
 // test trait_item
diff --git a/crates/ra_parser/src/grammar/items/use_item.rs b/crates/ra_parser/src/grammar/items/use_item.rs
index 63ac37e9e..e3b991c8c 100644
--- a/crates/ra_parser/src/grammar/items/use_item.rs
+++ b/crates/ra_parser/src/grammar/items/use_item.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use super::*;
 
 pub(super) fn use_item(p: &mut Parser, m: Marker) {
diff --git a/crates/ra_parser/src/grammar/params.rs b/crates/ra_parser/src/grammar/params.rs
index efc329243..c10b53316 100644
--- a/crates/ra_parser/src/grammar/params.rs
+++ b/crates/ra_parser/src/grammar/params.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use super::*;
 
 // test param_list
diff --git a/crates/ra_parser/src/grammar/paths.rs b/crates/ra_parser/src/grammar/paths.rs
index 24b65128e..ca8e075a1 100644
--- a/crates/ra_parser/src/grammar/paths.rs
+++ b/crates/ra_parser/src/grammar/paths.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use super::*;
 
 pub(super) const PATH_FIRST: TokenSet =
diff --git a/crates/ra_parser/src/grammar/patterns.rs b/crates/ra_parser/src/grammar/patterns.rs
index aa9a6d18e..f5d12278c 100644
--- a/crates/ra_parser/src/grammar/patterns.rs
+++ b/crates/ra_parser/src/grammar/patterns.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use super::*;
 
 pub(super) const PATTERN_FIRST: TokenSet = expressions::LITERAL_FIRST
diff --git a/crates/ra_parser/src/grammar/type_args.rs b/crates/ra_parser/src/grammar/type_args.rs
index 8e97fe03c..7256c2697 100644
--- a/crates/ra_parser/src/grammar/type_args.rs
+++ b/crates/ra_parser/src/grammar/type_args.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use super::*;
 
 pub(super) fn opt_type_arg_list(p: &mut Parser, colon_colon_required: bool) {
diff --git a/crates/ra_parser/src/grammar/type_params.rs b/crates/ra_parser/src/grammar/type_params.rs
index 7071c70ea..34406b5bd 100644
--- a/crates/ra_parser/src/grammar/type_params.rs
+++ b/crates/ra_parser/src/grammar/type_params.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use super::*;
 
 pub(super) fn opt_type_param_list(p: &mut Parser) {
diff --git a/crates/ra_parser/src/grammar/types.rs b/crates/ra_parser/src/grammar/types.rs
index 4e3522d48..d4ca94fca 100644
--- a/crates/ra_parser/src/grammar/types.rs
+++ b/crates/ra_parser/src/grammar/types.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use super::*;
 
 pub(super) const TYPE_FIRST: TokenSet = paths::PATH_FIRST.union(token_set![
diff --git a/crates/ra_parser/src/parser.rs b/crates/ra_parser/src/parser.rs
index f8fba6860..dafd5247b 100644
--- a/crates/ra_parser/src/parser.rs
+++ b/crates/ra_parser/src/parser.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::cell::Cell;
 
 use drop_bomb::DropBomb;
diff --git a/crates/ra_parser/src/syntax_kind.rs b/crates/ra_parser/src/syntax_kind.rs
index 3efcfa403..8d6bd057b 100644
--- a/crates/ra_parser/src/syntax_kind.rs
+++ b/crates/ra_parser/src/syntax_kind.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 #[macro_use]
 mod generated;
 
diff --git a/crates/ra_parser/src/syntax_kind/generated.rs b/crates/ra_parser/src/syntax_kind/generated.rs
index 8b43d93fe..96b5bce88 100644
--- a/crates/ra_parser/src/syntax_kind/generated.rs
+++ b/crates/ra_parser/src/syntax_kind/generated.rs
@@ -1,4 +1,4 @@
-// Generated file, do not edit by hand, see `crate/ra_tools/src/codegen`
+//! Generated file, do not edit by hand, see `crate/ra_tools/src/codegen`
 
 #![allow(bad_style, missing_docs, unreachable_pub)]
 #[doc = r" The kind of syntax node, e.g. `IDENT`, `USE_KW`, or `STRUCT_DEF`."]
diff --git a/crates/ra_parser/src/token_set.rs b/crates/ra_parser/src/token_set.rs
index 79121b35f..6dc061889 100644
--- a/crates/ra_parser/src/token_set.rs
+++ b/crates/ra_parser/src/token_set.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use crate::SyntaxKind;
 
 /// A bit-set of `SyntaxKind`s
diff --git a/crates/ra_prof/src/lib.rs b/crates/ra_prof/src/lib.rs
index d32a289be..885a98750 100644
--- a/crates/ra_prof/src/lib.rs
+++ b/crates/ra_prof/src/lib.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 mod memory_usage;
 #[cfg(feature = "cpu_profiler")]
 mod google_cpu_profiler;
diff --git a/crates/ra_prof/src/memory_usage.rs b/crates/ra_prof/src/memory_usage.rs
index 8e8cb7299..ad005ea14 100644
--- a/crates/ra_prof/src/memory_usage.rs
+++ b/crates/ra_prof/src/memory_usage.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::fmt;
 
 pub struct MemoryUsage {
diff --git a/crates/ra_project_model/src/cargo_workspace.rs b/crates/ra_project_model/src/cargo_workspace.rs
index 712d8818f..805eaa178 100644
--- a/crates/ra_project_model/src/cargo_workspace.rs
+++ b/crates/ra_project_model/src/cargo_workspace.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::path::{Path, PathBuf};
 
 use cargo_metadata::{CargoOpt, MetadataCommand};
diff --git a/crates/ra_project_model/src/json_project.rs b/crates/ra_project_model/src/json_project.rs
index 9a9eb9e1f..54ddca2cb 100644
--- a/crates/ra_project_model/src/json_project.rs
+++ b/crates/ra_project_model/src/json_project.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::path::PathBuf;
 
 use serde::Deserialize;
diff --git a/crates/ra_project_model/src/lib.rs b/crates/ra_project_model/src/lib.rs
index 4fa32dc34..5d3078598 100644
--- a/crates/ra_project_model/src/lib.rs
+++ b/crates/ra_project_model/src/lib.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 mod cargo_workspace;
 mod json_project;
 mod sysroot;
diff --git a/crates/ra_project_model/src/sysroot.rs b/crates/ra_project_model/src/sysroot.rs
index 0c27d4f4b..35d6df5cb 100644
--- a/crates/ra_project_model/src/sysroot.rs
+++ b/crates/ra_project_model/src/sysroot.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::{
     env,
     path::{Path, PathBuf},
diff --git a/crates/ra_syntax/fuzz/fuzz_targets/parser.rs b/crates/ra_syntax/fuzz/fuzz_targets/parser.rs
index 76a8b08d0..7bc4ef30d 100644
--- a/crates/ra_syntax/fuzz/fuzz_targets/parser.rs
+++ b/crates/ra_syntax/fuzz/fuzz_targets/parser.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 #![no_main]
 use libfuzzer_sys::fuzz_target;
 use ra_syntax::fuzz::check_parser;
diff --git a/crates/ra_syntax/fuzz/fuzz_targets/reparse.rs b/crates/ra_syntax/fuzz/fuzz_targets/reparse.rs
index 45524d4c1..16598f5f1 100644
--- a/crates/ra_syntax/fuzz/fuzz_targets/reparse.rs
+++ b/crates/ra_syntax/fuzz/fuzz_targets/reparse.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 #![no_main]
 use libfuzzer_sys::fuzz_target;
 use ra_syntax::fuzz::CheckReparse;
diff --git a/crates/ra_syntax/src/algo.rs b/crates/ra_syntax/src/algo.rs
index f33d2ad4e..d55534ede 100644
--- a/crates/ra_syntax/src/algo.rs
+++ b/crates/ra_syntax/src/algo.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 pub mod visit;
 
 use std::ops::RangeInclusive;
diff --git a/crates/ra_syntax/src/algo/visit.rs b/crates/ra_syntax/src/algo/visit.rs
index 87bd15cc0..4df275ba4 100644
--- a/crates/ra_syntax/src/algo/visit.rs
+++ b/crates/ra_syntax/src/algo/visit.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use crate::{AstNode, SyntaxNode};
 
 use std::marker::PhantomData;
diff --git a/crates/ra_syntax/src/ast/generated.rs b/crates/ra_syntax/src/ast/generated.rs
index aaf03ce3f..3bb5571ee 100644
--- a/crates/ra_syntax/src/ast/generated.rs
+++ b/crates/ra_syntax/src/ast/generated.rs
@@ -1,4 +1,4 @@
-// Generated file, do not edit by hand, see `crate/ra_tools/src/codegen`
+//! Generated file, do not edit by hand, see `crate/ra_tools/src/codegen`
 
 use crate::{
     ast::{self, AstChildren, AstNode},
diff --git a/crates/ra_syntax/src/fuzz.rs b/crates/ra_syntax/src/fuzz.rs
index 698a624ec..7012df7f0 100644
--- a/crates/ra_syntax/src/fuzz.rs
+++ b/crates/ra_syntax/src/fuzz.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use crate::{validation, AstNode, SourceFile, TextRange, TextUnit};
 use ra_text_edit::AtomTextEdit;
 use std::str::{self, FromStr};
diff --git a/crates/ra_syntax/src/parsing/lexer.rs b/crates/ra_syntax/src/parsing/lexer.rs
index bdb01d40b..6d839208d 100644
--- a/crates/ra_syntax/src/parsing/lexer.rs
+++ b/crates/ra_syntax/src/parsing/lexer.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use crate::{
     SyntaxKind::{self, *},
     TextUnit,
diff --git a/crates/ra_syntax/src/parsing/text_token_source.rs b/crates/ra_syntax/src/parsing/text_token_source.rs
index 64cb20ae8..e793f93a4 100644
--- a/crates/ra_syntax/src/parsing/text_token_source.rs
+++ b/crates/ra_syntax/src/parsing/text_token_source.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use ra_parser::Token as PToken;
 use ra_parser::TokenSource;
 
diff --git a/crates/ra_syntax/src/parsing/text_tree_sink.rs b/crates/ra_syntax/src/parsing/text_tree_sink.rs
index be6e51780..142164316 100644
--- a/crates/ra_syntax/src/parsing/text_tree_sink.rs
+++ b/crates/ra_syntax/src/parsing/text_tree_sink.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::mem;
 
 use ra_parser::{ParseError, TreeSink};
diff --git a/crates/ra_syntax/src/ptr.rs b/crates/ra_syntax/src/ptr.rs
index 992034ef0..31167cada 100644
--- a/crates/ra_syntax/src/ptr.rs
+++ b/crates/ra_syntax/src/ptr.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::{iter::successors, marker::PhantomData};
 
 use crate::{AstNode, SyntaxKind, SyntaxNode, TextRange};
diff --git a/crates/ra_syntax/src/syntax_error.rs b/crates/ra_syntax/src/syntax_error.rs
index 5aefec768..d6eca2ad7 100644
--- a/crates/ra_syntax/src/syntax_error.rs
+++ b/crates/ra_syntax/src/syntax_error.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::fmt;
 
 use ra_parser::ParseError;
diff --git a/crates/ra_syntax/src/validation.rs b/crates/ra_syntax/src/validation.rs
index 16824f3c4..4f8935b2c 100644
--- a/crates/ra_syntax/src/validation.rs
+++ b/crates/ra_syntax/src/validation.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 mod block;
 
 use rustc_lexer::unescape;
diff --git a/crates/ra_syntax/src/validation/block.rs b/crates/ra_syntax/src/validation/block.rs
index 3c9e96eb3..c85bbc1f4 100644
--- a/crates/ra_syntax/src/validation/block.rs
+++ b/crates/ra_syntax/src/validation/block.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use crate::{
     ast::{self, AstNode, AttrsOwner},
     SyntaxError,
diff --git a/crates/ra_text_edit/src/lib.rs b/crates/ra_text_edit/src/lib.rs
index df673ba18..5f1b12222 100644
--- a/crates/ra_text_edit/src/lib.rs
+++ b/crates/ra_text_edit/src/lib.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 mod text_edit;
 pub mod test_utils;
 
diff --git a/crates/ra_text_edit/src/test_utils.rs b/crates/ra_text_edit/src/test_utils.rs
index 2d6e7f216..d4c7840ff 100644
--- a/crates/ra_text_edit/src/test_utils.rs
+++ b/crates/ra_text_edit/src/test_utils.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use crate::{AtomTextEdit, TextEdit};
 use proptest::prelude::*;
 use text_unit::{TextRange, TextUnit};
diff --git a/crates/ra_text_edit/src/text_edit.rs b/crates/ra_text_edit/src/text_edit.rs
index 8522f99bd..0381ea000 100644
--- a/crates/ra_text_edit/src/text_edit.rs
+++ b/crates/ra_text_edit/src/text_edit.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use crate::AtomTextEdit;
 use text_unit::{TextRange, TextUnit};
 
diff --git a/crates/ra_tools/src/bin/pre-commit.rs b/crates/ra_tools/src/bin/pre-commit.rs
index a628f64b2..16bbf9cb2 100644
--- a/crates/ra_tools/src/bin/pre-commit.rs
+++ b/crates/ra_tools/src/bin/pre-commit.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::process::Command;
 
 use ra_tools::{project_root, run, run_rustfmt, Overwrite, Result};
diff --git a/crates/ra_tools/src/boilerplate_gen.rs b/crates/ra_tools/src/boilerplate_gen.rs
index 1d112c0af..39f1cae66 100644
--- a/crates/ra_tools/src/boilerplate_gen.rs
+++ b/crates/ra_tools/src/boilerplate_gen.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use std::{
     collections::BTreeMap,
     fs,
@@ -282,7 +284,7 @@ fn reformat(text: impl std::fmt::Display) -> Result<String> {
     let output = rustfmt.wait_with_output()?;
     let stdout = String::from_utf8(output.stdout)?;
     let preamble = "Generated file, do not edit by hand, see `crate/ra_tools/src/codegen`";
-    Ok(format!("// {}\n\n{}", preamble, stdout))
+    Ok(format!("//! {}\n\n{}", preamble, stdout))
 }
 
 #[derive(Deserialize, Debug)]
diff --git a/crates/ra_tools/src/help.rs b/crates/ra_tools/src/help.rs
index 9eb4dfbe4..72dfabacd 100644
--- a/crates/ra_tools/src/help.rs
+++ b/crates/ra_tools/src/help.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 pub const GLOBAL_HELP: &str = "tasks
 
 USAGE:
diff --git a/crates/ra_tools/src/lib.rs b/crates/ra_tools/src/lib.rs
index 9ba23caaa..aa993a38a 100644
--- a/crates/ra_tools/src/lib.rs
+++ b/crates/ra_tools/src/lib.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 mod boilerplate_gen;
 
 use std::{
diff --git a/crates/ra_tools/src/main.rs b/crates/ra_tools/src/main.rs
index a951ce427..161871ccf 100644
--- a/crates/ra_tools/src/main.rs
+++ b/crates/ra_tools/src/main.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 mod help;
 
 use core::fmt::Write;
diff --git a/crates/ra_tools/tests/cli.rs b/crates/ra_tools/tests/cli.rs
index 91b19c8f8..609fd4d8b 100644
--- a/crates/ra_tools/tests/cli.rs
+++ b/crates/ra_tools/tests/cli.rs
@@ -1,6 +1,5 @@
-use walkdir::WalkDir;
-
 use ra_tools::{gen_tests, generate_boilerplate, project_root, run_rustfmt, Verify};
+use walkdir::WalkDir;
 
 #[test]
 fn generated_grammar_is_fresh() {
@@ -36,7 +35,7 @@ fn no_todo() {
         let text = std::fs::read_to_string(e.path()).unwrap();
         if text.contains("TODO") || text.contains("TOOD") {
             panic!(
-                "\nTODO markers should not be commited to the master branch,\n\
+                "\nTODO markers should not be committed to the master branch,\n\
                  use FIXME instead\n\
                  {}\n",
                 e.path().display(),
diff --git a/crates/ra_tools/tests/docs.rs b/crates/ra_tools/tests/docs.rs
new file mode 100644
index 000000000..ea3330175
--- /dev/null
+++ b/crates/ra_tools/tests/docs.rs
@@ -0,0 +1,63 @@
+use std::fs;
+use std::io::prelude::*;
+use std::io::BufReader;
+use std::path::Path;
+
+use walkdir::{DirEntry, WalkDir};
+
+use ra_tools::project_root;
+
+fn is_exclude_dir(p: &Path) -> bool {
+    let exclude_dirs = ["tests", "test_data"];
+    let mut cur_path = p;
+    while let Some(path) = cur_path.parent() {
+        if exclude_dirs.iter().any(|dir| path.ends_with(dir)) {
+            return true;
+        }
+        cur_path = path;
+    }
+
+    false
+}
+
+fn is_exclude_file(d: &DirEntry) -> bool {
+    let file_names = ["tests.rs"];
+
+    d.file_name().to_str().map(|f_n| file_names.iter().any(|name| *name == f_n)).unwrap_or(false)
+}
+
+fn is_hidden(entry: &DirEntry) -> bool {
+    entry.file_name().to_str().map(|s| s.starts_with(".")).unwrap_or(false)
+}
+
+#[test]
+fn no_docs_comments() {
+    let crates = project_root().join("crates");
+    let iter = WalkDir::new(crates);
+    for f in iter.into_iter().filter_entry(|e| !is_hidden(e)) {
+        let f = f.unwrap();
+        if f.file_type().is_dir() {
+            continue;
+        }
+        if f.path().extension().map(|it| it != "rs").unwrap_or(false) {
+            continue;
+        }
+        if is_exclude_dir(f.path()) {
+            continue;
+        }
+        if is_exclude_file(&f) {
+            continue;
+        }
+        let mut reader = BufReader::new(fs::File::open(f.path()).unwrap());
+        let mut line = String::new();
+        reader.read_line(&mut line).unwrap();
+        if !line.starts_with("//!") {
+            panic!(
+                "\nMissing docs strings\n\
+                 module: {}\n\
+                 Need add doc for module\n",
+                f.path().display()
+            )
+        }
+    }
+}
diff --git a/crates/ra_tools/tests/main.rs b/crates/ra_tools/tests/main.rs
new file mode 100644
index 000000000..56d1318d6
--- /dev/null
+++ b/crates/ra_tools/tests/main.rs
@@ -0,0 +1,2 @@
+mod cli;
+mod docs;
diff --git a/crates/ra_tt/src/buffer.rs b/crates/ra_tt/src/buffer.rs
index 48c22a2d8..ef3f2323c 100644
--- a/crates/ra_tt/src/buffer.rs
+++ b/crates/ra_tt/src/buffer.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 use crate::{Subtree, TokenTree};
 
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
diff --git a/crates/ra_tt/src/lib.rs b/crates/ra_tt/src/lib.rs
index 2a48c66c4..20c251ff4 100644
--- a/crates/ra_tt/src/lib.rs
+++ b/crates/ra_tt/src/lib.rs
@@ -1,6 +1,6 @@
-/// `tt` crate defines a `TokenTree` data structure: this is the interface (both
-/// input and output) of macros. It closely mirrors `proc_macro` crate's
-/// `TokenTree`.
+//! `tt` crate defines a `TokenTree` data structure: this is the interface (both
+//! input and output) of macros. It closely mirrors `proc_macro` crate's
+//! `TokenTree`.
 
 macro_rules! impl_froms {
     ($e:ident: $($v:ident), *) => {
diff --git a/crates/test_utils/src/lib.rs b/crates/test_utils/src/lib.rs
index 816d01f09..c40943b63 100644
--- a/crates/test_utils/src/lib.rs
+++ b/crates/test_utils/src/lib.rs
@@ -1,3 +1,5 @@
+//! FIXME: write short doc here
+
 #[macro_use]
 pub mod marks;