diff --git a/crates/ra_assists/src/assist_ctx.rs b/crates/ra_assists/src/assist_ctx.rs
index 5f564be0b2..189cad7d04 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 8f2c6266e4..77ecc33c9d 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 78f0f7f28a..8c83dc9878 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 4b61f40314..94801fbc9a 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 6fd1c37530..565b96fb50 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 419e93330b..02c58e7c6d 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 60c74debca..df92c6b67c 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 db82db89ab..7335cce094 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 b55b36a8ed..c510352823 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 5ee7561bc4..e31cc5e7d7 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 eedb291994..9bd64decc9 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 470ffe120c..43378c4b05 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 3b6a99895d..17baa98f92 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 39ff512335..f791d22b0b 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 699221e335..51aea63340 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 965a64c987..388ee7e97b 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 870133fda0..1a7e2b3050 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 401835c579..749ff338aa 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 2c1edddb90..19d429daf5 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 a29f9f6586..c20e4db9e9 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 ffc9e16bba..939f72037d 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 01b96ec586..727f1e62b8 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 6b1e44a2c5..a8a110bd93 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 2a74b8733a..d3c4c7d0bb 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 8b91ba3e95..e6c76087ec 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 a1ace61b65..52f8928914 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 fd7afcbb64..e3a7e8e3ca 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 99edc58140..9675e397fc 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 dc964e1566..fdae269060 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 deed1c62f8..73d7d6fb66 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 60da336954..9acdaf8ed3 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 439e6ec872..83583ef8bd 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 b1bec2a68d..d238741bab 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 6d6f605065..50ea429ea1 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 de0983a7ed..5496822e72 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 f06e5ec07e..1aa853c3e9 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 7b6d9b2407..a012f33f7b 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 bcbcd3dd77..a3b65cc794 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 c66a1c6a6d..8cf74ddc7f 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 dbba433fe0..6c4e8ffbd3 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 a9de9fb6b1..00031debab 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 0fed468026..79af24b201 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 cb405091ee..50feb98fb3 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 d50867f5dc..1e0b8c3506 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 65929c522b..a568fdabda 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 964da2794e..0da6789de6 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 0e27dd2db3..606bd1a958 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 158c853d42..394617e1a4 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 6e89bfc765..088335e667 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 04574876da..a4dd99598c 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 63ec9d7e1d..7910429d72 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 1b30a5b9b7..bcfa3a6a2a 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 2c60fefd61..8966f9d1d5 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 e3d1ac5298..e00589733b 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 d5e1165266..7d18be483c 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 981851829a..09913787b7 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 0ad4148311..abe1f36cec 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 9e64c86590..28c8324d02 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 6639b6fffe..844a63f6c8 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 c527a9f631..3f121d45c1 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 0cbe4abf7d..d808b23571 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 e9fec54d86..e01197fe48 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 c17b5b7ee4..513ad6e5f0 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 3970d1af34..445a026768 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 ed40299647..4406695d51 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 70716b3d60..d20fa796c7 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 cb70a1f212..515a6285c1 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 b06221c2a6..2df79b6c3f 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 57542152f7..e9ad069655 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 d787bb69ed..b1f0390ecd 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 b8aa433c18..48028a2f9c 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 afd9022ce4..ea0714addb 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 4fa07e3dc1..0435188c84 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 644a4532b6..43f022ccd4 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 d3e774bd0d..60ae802c06 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 b16d504e14..5d2bce3d29 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 38a56d7524..8815df747e 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 e990eb0d13..33fefb5416 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 9f82ac71c1..d3ca7be031 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 79fadcc5db..4eeb76d143 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 bc8863dadb..567d4a6748 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 72884e5ca9..059d80524e 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 655bcdb16d..200b57679b 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 f57f9a21b6..7fc1b1efa8 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 16bdcf9d16..9b45575f82 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 a71e4ed7dc..6f71b27db2 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 5fedad6965..710890d27d 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 534009b98d..bd1e08feba 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 c3752cc541..3f4ba248b3 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 e802d01e4d..d1204fac01 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 132f6f875b..16870c7ae4 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 aff03464ae..149585971e 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 3668da8d74..c85f1d0d02 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 acca71f2a8..84c2eb7936 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 8cf58fe795..910883da74 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 dee2ea46a9..f91f16c8e4 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 3d7f91c1de..9ae2dc0610 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 e2bb120b4b..4d0f0fc47d 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 6e0d883b46..8adb214d4c 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 2d4491442c..2f5782012b 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 592dddf44b..088cc9be40 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 22fc97a97f..30bcbd7a82 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 a083bb3112..d996b53de4 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 cf53e7c4ce..579d4c6926 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 d78f779255..1318a17389 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 fa3d88abd8..7a71a90fb5 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 852fae0277..7d9a1d054d 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 2059f98001..35c35d32bb 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 ae57e57e95..10e2713766 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 7a99fc6799..e7ea7aa5b8 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 bbeda723c9..3856263b0a 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 3659edf8ef..f51fc4ade3 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 0540f166ee..d25fc57269 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 232409c3be..b55046ec9a 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 a0904323cb..afdbee84e3 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 aff9531029..0548e8512e 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 cf74589051..7ef45f6dc4 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 2d035307b1..1b543c84b8 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 c53f99d1ea..319f1ee65f 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 63ca9ca321..f3158ade30 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 80b085280d..413ecb2782 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 457f42a26a..a52bdb3ea3 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 4c67a5c2e2..85f7eeb002 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 310260689e..742a7e0562 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 bede3b6927..9d8fb84869 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 3742fd197f..2c560e8247 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 63ac37e9e1..e3b991c8c6 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 efc3292438..c10b53316a 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 24b65128ed..ca8e075a1a 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 aa9a6d18e0..f5d12278c8 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 8e97fe03c0..7256c2697c 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 7071c70eaf..34406b5bd5 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 4e3522d487..d4ca94fca5 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 f8fba6860b..dafd5247bf 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 3efcfa4030..8d6bd057b3 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 8b43d93fe5..96b5bce88d 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 79121b35f2..6dc061889f 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 d32a289be7..885a987500 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 8e8cb72997..ad005ea14f 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 712d8818f8..805eaa1780 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 9a9eb9e1fd..54ddca2cb6 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 4fa32dc340..5d30785980 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 0c27d4f4b3..35d6df5cb5 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 76a8b08d00..7bc4ef30d0 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 45524d4c12..16598f5f11 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 f33d2ad4e3..d55534ede8 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 87bd15cc0c..4df275ba4f 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 aaf03ce3f4..3bb5571ee6 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 698a624ecc..7012df7f02 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 bdb01d40b3..6d839208dd 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 64cb20ae8c..e793f93a4d 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 be6e517803..1421643163 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 992034ef0f..31167cada0 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 5aefec768f..d6eca2ad77 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 16824f3c40..4f8935b2ca 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 3c9e96eb30..c85bbc1f4f 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 df673ba185..5f1b122221 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 2d6e7f2163..d4c7840ffa 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 8522f99bdd..0381ea0008 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 a628f64b24..16bbf9cb27 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 1d112c0af6..39f1cae665 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 9eb4dfbe42..72dfabacd2 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 9ba23caaa9..aa993a38ab 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 a951ce4270..161871ccf2 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 91b19c8f82..609fd4d8bc 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 0000000000..ea33301750
--- /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 0000000000..56d1318d62
--- /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 48c22a2d8a..ef3f2323c9 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 2a48c66c48..20c251ff45 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 816d01f09e..c40943b63c 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;