31 files changed, 426 insertions, 115 deletions
diff --git a/crates/ra_syntax/src/ast.rs b/crates/ra_syntax/src/ast.rs
index 3e948800e..c10169d90 100644
--- a/crates/ra_syntax/src/ast.rs
+++ b/crates/ra_syntax/src/ast.rs
@@ -30,6 +30,12 @@ pub trait NameOwner<'a>: AstNode<'a> {
    }
 }
+pub trait VisibilityOwner<'a>: AstNode<'a> {
+    fn visibility(self) -> Option<Visibility<'a>> {
+        child_opt(self)
+    }
+}
 pub trait LoopBodyOwner<'a>: AstNode<'a> {
    fn loop_body(self) -> Option<Block<'a>> {
        child_opt(self)
@@ -109,6 +115,7 @@ pub trait DocCommentsOwner<'a>: AstNode<'a> {
    /// That is, strips leading `///` and joins lines
    fn doc_comment_text(self) -> RustString {
        self.doc_comments()
+            .filter(|comment| comment.is_doc_comment())
            .map(|comment| {
                let prefix = comment.prefix();
                let trimmed = comment
@@ -200,6 +207,10 @@ impl<'a> Comment<'a> {
        }
    }
+    pub fn is_doc_comment(&self) -> bool {
+        self.flavor().is_doc_comment()
+    }
    pub fn prefix(&self) -> &'static str {
        self.flavor().prefix()
    }
@@ -231,6 +242,13 @@ impl CommentFlavor {
            Multiline => "/*",
        }
    }
+    pub fn is_doc_comment(&self) -> bool {
+        match self {
+            CommentFlavor::Doc | CommentFlavor::ModuleDoc => true,
+            _ => false,
+        }
+    }
 }
 impl<'a> Whitespace<'a> {
@@ -261,7 +279,7 @@ impl<'a> NameRef<'a> {
    }
 }
-impl<'a> ImplItem<'a> {
+impl<'a> ImplBlock<'a> {
    pub fn target_type(self) -> Option<TypeRef<'a>> {
        match self.target() {
            (Some(t), None) | (_, Some(t)) => Some(t),
@@ -345,6 +363,12 @@ impl<'a> PathSegment<'a> {
    }
 }
+impl<'a> Path<'a> {
+    pub fn parent_path(self) -> Option<Path<'a>> {
+        self.syntax().parent().and_then(Path::cast)
+    }
+}
 impl<'a> UseTree<'a> {
    pub fn has_star(self) -> bool {
        self.syntax().children().any(|it| it.kind() == STAR)
@@ -463,3 +487,47 @@ impl<'a> PrefixExpr<'a> {
        }
    }
 }
+#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
+pub enum SelfParamFlavor {
+    /// self
+    Owned,
+    /// &self
+    Ref,
+    /// &mut self
+    MutRef,
+}
+impl<'a> SelfParam<'a> {
+    pub fn flavor(&self) -> SelfParamFlavor {
+        let borrowed = self.syntax().children().any(|n| n.kind() == AMP);
+        if borrowed {
+            // check for a `mut` coming after the & -- `mut &self` != `&mut self`
+            if self
+                .syntax()
+                .children()
+                .skip_while(|n| n.kind() != AMP)
+                .any(|n| n.kind() == MUT_KW)
+            {
+                SelfParamFlavor::MutRef
+            } else {
+                SelfParamFlavor::Ref
+            }
+        } else {
+            SelfParamFlavor::Owned
+        }
+    }
+}
+#[test]
+fn test_doc_comment_of_items() {
+    let file = SourceFileNode::parse(
+        r#"
+        //! doc
+        // non-doc
+        mod foo {}
+        "#,
+    );
+    let module = file.syntax().descendants().find_map(Module::cast).unwrap();
+    assert_eq!("doc", module.doc_comment_text());
+}
diff --git a/crates/ra_syntax/src/ast/generated.rs b/crates/ra_syntax/src/ast/generated.rs
index c5ac90a62..7df6a9c46 100644
--- a/crates/ra_syntax/src/ast/generated.rs
+++ b/crates/ra_syntax/src/ast/generated.rs
@@ -695,6 +695,7 @@ impl<R: TreeRoot<RaTypes>> ConstDefNode<R> {
 }
+impl<'a> ast::VisibilityOwner<'a> for ConstDef<'a> {}
 impl<'a> ast::NameOwner<'a> for ConstDef<'a> {}
 impl<'a> ast::TypeParamsOwner<'a> for ConstDef<'a> {}
 impl<'a> ast::AttrsOwner<'a> for ConstDef<'a> {}
@@ -810,6 +811,7 @@ impl<R: TreeRoot<RaTypes>> EnumDefNode<R> {
 }
+impl<'a> ast::VisibilityOwner<'a> for EnumDef<'a> {}
 impl<'a> ast::NameOwner<'a> for EnumDef<'a> {}
 impl<'a> ast::TypeParamsOwner<'a> for EnumDef<'a> {}
 impl<'a> ast::AttrsOwner<'a> for EnumDef<'a> {}
@@ -1213,6 +1215,7 @@ impl<R: TreeRoot<RaTypes>> FnDefNode<R> {
 }
+impl<'a> ast::VisibilityOwner<'a> for FnDef<'a> {}
 impl<'a> ast::NameOwner<'a> for FnDef<'a> {}
 impl<'a> ast::TypeParamsOwner<'a> for FnDef<'a> {}
 impl<'a> ast::AttrsOwner<'a> for FnDef<'a> {}
@@ -1404,40 +1407,72 @@ impl<'a> IfExpr<'a> {
    }
 }
-// ImplItem
+// ImplBlock
 #[derive(Debug, Clone, Copy,)]
-pub struct ImplItemNode<R: TreeRoot<RaTypes> = OwnedRoot> {
+pub struct ImplBlockNode<R: TreeRoot<RaTypes> = OwnedRoot> {
    pub(crate) syntax: SyntaxNode<R>,
 }
-pub type ImplItem<'a> = ImplItemNode<RefRoot<'a>>;
+pub type ImplBlock<'a> = ImplBlockNode<RefRoot<'a>>;
-impl<R1: TreeRoot<RaTypes>, R2: TreeRoot<RaTypes>> PartialEq<ImplItemNode<R1>> for ImplItemNode<R2> {
+impl<R1: TreeRoot<RaTypes>, R2: TreeRoot<RaTypes>> PartialEq<ImplBlockNode<R1>> for ImplBlockNode<R2> {
-    fn eq(&self, other: &ImplItemNode<R1>) -> bool { self.syntax == other.syntax }
+    fn eq(&self, other: &ImplBlockNode<R1>) -> bool { self.syntax == other.syntax }
 }
-impl<R: TreeRoot<RaTypes>> Eq for ImplItemNode<R> {}
+impl<R: TreeRoot<RaTypes>> Eq for ImplBlockNode<R> {}
-impl<R: TreeRoot<RaTypes>> Hash for ImplItemNode<R> {
+impl<R: TreeRoot<RaTypes>> Hash for ImplBlockNode<R> {
    fn hash<H: Hasher>(&self, state: &mut H) { self.syntax.hash(state) }
 }
-impl<'a> AstNode<'a> for ImplItem<'a> {
+impl<'a> AstNode<'a> for ImplBlock<'a> {
    fn cast(syntax: SyntaxNodeRef<'a>) -> Option<Self> {
        match syntax.kind() {
-            IMPL_ITEM => Some(ImplItem { syntax }),
+            IMPL_BLOCK => Some(ImplBlock { syntax }),
            _ => None,
        }
    }
    fn syntax(self) -> SyntaxNodeRef<'a> { self.syntax }
 }
-impl<R: TreeRoot<RaTypes>> ImplItemNode<R> {
+impl<R: TreeRoot<RaTypes>> ImplBlockNode<R> {
-    pub fn borrowed(&self) -> ImplItem {
+    pub fn borrowed(&self) -> ImplBlock {
-        ImplItemNode { syntax: self.syntax.borrowed() }
+        ImplBlockNode { syntax: self.syntax.borrowed() }
+    }
+    pub fn owned(&self) -> ImplBlockNode {
+        ImplBlockNode { syntax: self.syntax.owned() }
    }
-    pub fn owned(&self) -> ImplItemNode {
+}
-        ImplItemNode { syntax: self.syntax.owned() }
+impl<'a> ImplBlock<'a> {
+    pub fn item_list(self) -> Option<ItemList<'a>> {
+        super::child_opt(self)
    }
 }
+// ImplItem
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ImplItem<'a> {
+    FnDef(FnDef<'a>),
+    TypeDef(TypeDef<'a>),
+    ConstDef(ConstDef<'a>),
+}
+impl<'a> AstNode<'a> for ImplItem<'a> {
+    fn cast(syntax: SyntaxNodeRef<'a>) -> Option<Self> {
+        match syntax.kind() {
+            FN_DEF => Some(ImplItem::FnDef(FnDef { syntax })),
+            TYPE_DEF => Some(ImplItem::TypeDef(TypeDef { syntax })),
+            CONST_DEF => Some(ImplItem::ConstDef(ConstDef { syntax })),
+            _ => None,
+        }
+    }
+    fn syntax(self) -> SyntaxNodeRef<'a> {
+        match self {
+            ImplItem::FnDef(inner) => inner.syntax(),
+            ImplItem::TypeDef(inner) => inner.syntax(),
+            ImplItem::ConstDef(inner) => inner.syntax(),
+        }
+    }
+}
 impl<'a> ImplItem<'a> {}
@@ -1552,7 +1587,11 @@ impl<R: TreeRoot<RaTypes>> ItemListNode<R> {
 impl<'a> ast::FnDefOwner<'a> for ItemList<'a> {}
 impl<'a> ast::ModuleItemOwner<'a> for ItemList<'a> {}
-impl<'a> ItemList<'a> {}
+impl<'a> ItemList<'a> {
+    pub fn impl_items(self) -> impl Iterator<Item = ImplItem<'a>> + 'a {
+        super::children(self)
+    }
+}
 // Label
 #[derive(Debug, Clone, Copy,)]
@@ -2136,6 +2175,7 @@ impl<R: TreeRoot<RaTypes>> ModuleNode<R> {
 }
+impl<'a> ast::VisibilityOwner<'a> for Module<'a> {}
 impl<'a> ast::NameOwner<'a> for Module<'a> {}
 impl<'a> ast::AttrsOwner<'a> for Module<'a> {}
 impl<'a> ast::DocCommentsOwner<'a> for Module<'a> {}
@@ -2153,7 +2193,7 @@ pub enum ModuleItem<'a> {
    FnDef(FnDef<'a>),
    TraitDef(TraitDef<'a>),
    TypeDef(TypeDef<'a>),
-    ImplItem(ImplItem<'a>),
+    ImplBlock(ImplBlock<'a>),
    UseItem(UseItem<'a>),
    ExternCrateItem(ExternCrateItem<'a>),
    ConstDef(ConstDef<'a>),
@@ -2169,7 +2209,7 @@ impl<'a> AstNode<'a> for ModuleItem<'a> {
            FN_DEF => Some(ModuleItem::FnDef(FnDef { syntax })),
            TRAIT_DEF => Some(ModuleItem::TraitDef(TraitDef { syntax })),
            TYPE_DEF => Some(ModuleItem::TypeDef(TypeDef { syntax })),
-            IMPL_ITEM => Some(ModuleItem::ImplItem(ImplItem { syntax })),
+            IMPL_BLOCK => Some(ModuleItem::ImplBlock(ImplBlock { syntax })),
            USE_ITEM => Some(ModuleItem::UseItem(UseItem { syntax })),
            EXTERN_CRATE_ITEM => Some(ModuleItem::ExternCrateItem(ExternCrateItem { syntax })),
            CONST_DEF => Some(ModuleItem::ConstDef(ConstDef { syntax })),
@@ -2185,7 +2225,7 @@ impl<'a> AstNode<'a> for ModuleItem<'a> {
            ModuleItem::FnDef(inner) => inner.syntax(),
            ModuleItem::TraitDef(inner) => inner.syntax(),
            ModuleItem::TypeDef(inner) => inner.syntax(),
-            ModuleItem::ImplItem(inner) => inner.syntax(),
+            ModuleItem::ImplBlock(inner) => inner.syntax(),
            ModuleItem::UseItem(inner) => inner.syntax(),
            ModuleItem::ExternCrateItem(inner) => inner.syntax(),
            ModuleItem::ConstDef(inner) => inner.syntax(),
@@ -2351,6 +2391,7 @@ impl<R: TreeRoot<RaTypes>> NamedFieldDefNode<R> {
 }
+impl<'a> ast::VisibilityOwner<'a> for NamedFieldDef<'a> {}
 impl<'a> ast::NameOwner<'a> for NamedFieldDef<'a> {}
 impl<'a> ast::AttrsOwner<'a> for NamedFieldDef<'a> {}
 impl<'a> NamedFieldDef<'a> {
@@ -3082,6 +3123,7 @@ impl<R: TreeRoot<RaTypes>> PosFieldNode<R> {
 }
+impl<'a> ast::VisibilityOwner<'a> for PosField<'a> {}
 impl<'a> ast::AttrsOwner<'a> for PosField<'a> {}
 impl<'a> PosField<'a> {
    pub fn type_ref(self) -> Option<TypeRef<'a>> {
@@ -3446,6 +3488,43 @@ impl<'a> ReturnExpr<'a> {
    }
 }
+// SelfKw
+#[derive(Debug, Clone, Copy,)]
+pub struct SelfKwNode<R: TreeRoot<RaTypes> = OwnedRoot> {
+    pub(crate) syntax: SyntaxNode<R>,
+}
+pub type SelfKw<'a> = SelfKwNode<RefRoot<'a>>;
+impl<R1: TreeRoot<RaTypes>, R2: TreeRoot<RaTypes>> PartialEq<SelfKwNode<R1>> for SelfKwNode<R2> {
+    fn eq(&self, other: &SelfKwNode<R1>) -> bool { self.syntax == other.syntax }
+}
+impl<R: TreeRoot<RaTypes>> Eq for SelfKwNode<R> {}
+impl<R: TreeRoot<RaTypes>> Hash for SelfKwNode<R> {
+    fn hash<H: Hasher>(&self, state: &mut H) { self.syntax.hash(state) }
+}
+impl<'a> AstNode<'a> for SelfKw<'a> {
+    fn cast(syntax: SyntaxNodeRef<'a>) -> Option<Self> {
+        match syntax.kind() {
+            SELF_KW => Some(SelfKw { syntax }),
+            _ => None,
+        }
+    }
+    fn syntax(self) -> SyntaxNodeRef<'a> { self.syntax }
+}
+impl<R: TreeRoot<RaTypes>> SelfKwNode<R> {
+    pub fn borrowed(&self) -> SelfKw {
+        SelfKwNode { syntax: self.syntax.borrowed() }
+    }
+    pub fn owned(&self) -> SelfKwNode {
+        SelfKwNode { syntax: self.syntax.owned() }
+    }
+}
+impl<'a> SelfKw<'a> {}
 // SelfParam
 #[derive(Debug, Clone, Copy,)]
 pub struct SelfParamNode<R: TreeRoot<RaTypes> = OwnedRoot> {
@@ -3481,7 +3560,15 @@ impl<R: TreeRoot<RaTypes>> SelfParamNode<R> {
 }
-impl<'a> SelfParam<'a> {}
+impl<'a> SelfParam<'a> {
+    pub fn type_ref(self) -> Option<TypeRef<'a>> {
+        super::child_opt(self)
+    }
+    pub fn self_kw(self) -> Option<SelfKw<'a>> {
+        super::child_opt(self)
+    }
+}
 // SlicePat
 #[derive(Debug, Clone, Copy,)]
@@ -3639,6 +3726,7 @@ impl<R: TreeRoot<RaTypes>> StaticDefNode<R> {
 }
+impl<'a> ast::VisibilityOwner<'a> for StaticDef<'a> {}
 impl<'a> ast::NameOwner<'a> for StaticDef<'a> {}
 impl<'a> ast::TypeParamsOwner<'a> for StaticDef<'a> {}
 impl<'a> ast::AttrsOwner<'a> for StaticDef<'a> {}
@@ -3742,6 +3830,7 @@ impl<R: TreeRoot<RaTypes>> StructDefNode<R> {
 }
+impl<'a> ast::VisibilityOwner<'a> for StructDef<'a> {}
 impl<'a> ast::NameOwner<'a> for StructDef<'a> {}
 impl<'a> ast::TypeParamsOwner<'a> for StructDef<'a> {}
 impl<'a> ast::AttrsOwner<'a> for StructDef<'a> {}
@@ -3902,6 +3991,7 @@ impl<R: TreeRoot<RaTypes>> TraitDefNode<R> {
 }
+impl<'a> ast::VisibilityOwner<'a> for TraitDef<'a> {}
 impl<'a> ast::NameOwner<'a> for TraitDef<'a> {}
 impl<'a> ast::AttrsOwner<'a> for TraitDef<'a> {}
 impl<'a> ast::DocCommentsOwner<'a> for TraitDef<'a> {}
@@ -4135,6 +4225,7 @@ impl<R: TreeRoot<RaTypes>> TypeDefNode<R> {
 }
+impl<'a> ast::VisibilityOwner<'a> for TypeDef<'a> {}
 impl<'a> ast::NameOwner<'a> for TypeDef<'a> {}
 impl<'a> ast::TypeParamsOwner<'a> for TypeDef<'a> {}
 impl<'a> ast::AttrsOwner<'a> for TypeDef<'a> {}
@@ -4409,6 +4500,43 @@ impl<'a> UseTreeList<'a> {
    }
 }
+// Visibility
+#[derive(Debug, Clone, Copy,)]
+pub struct VisibilityNode<R: TreeRoot<RaTypes> = OwnedRoot> {
+    pub(crate) syntax: SyntaxNode<R>,
+}
+pub type Visibility<'a> = VisibilityNode<RefRoot<'a>>;
+impl<R1: TreeRoot<RaTypes>, R2: TreeRoot<RaTypes>> PartialEq<VisibilityNode<R1>> for VisibilityNode<R2> {
+    fn eq(&self, other: &VisibilityNode<R1>) -> bool { self.syntax == other.syntax }
+}
+impl<R: TreeRoot<RaTypes>> Eq for VisibilityNode<R> {}
+impl<R: TreeRoot<RaTypes>> Hash for VisibilityNode<R> {
+    fn hash<H: Hasher>(&self, state: &mut H) { self.syntax.hash(state) }
+}
+impl<'a> AstNode<'a> for Visibility<'a> {
+    fn cast(syntax: SyntaxNodeRef<'a>) -> Option<Self> {
+        match syntax.kind() {
+            VISIBILITY => Some(Visibility { syntax }),
+            _ => None,
+        }
+    }
+    fn syntax(self) -> SyntaxNodeRef<'a> { self.syntax }
+}
+impl<R: TreeRoot<RaTypes>> VisibilityNode<R> {
+    pub fn borrowed(&self) -> Visibility {
+        VisibilityNode { syntax: self.syntax.borrowed() }
+    }
+    pub fn owned(&self) -> VisibilityNode {
+        VisibilityNode { syntax: self.syntax.owned() }
+    }
+}
+impl<'a> Visibility<'a> {}
 // WhereClause
 #[derive(Debug, Clone, Copy,)]
 pub struct WhereClauseNode<R: TreeRoot<RaTypes> = OwnedRoot> {
diff --git a/crates/ra_syntax/src/grammar.ron b/crates/ra_syntax/src/grammar.ron
index aab4839a9..c55e9e07a 100644
--- a/crates/ra_syntax/src/grammar.ron
+++ b/crates/ra_syntax/src/grammar.ron
@@ -128,7 +128,7 @@ Grammar(
        "STATIC_DEF",
        "CONST_DEF",
        "TRAIT_DEF",
-        "IMPL_ITEM",
+        "IMPL_BLOCK",
        "TYPE_DEF",
        "MACRO_CALL",
        "TOKEN_TREE",
@@ -247,6 +247,7 @@ Grammar(
        ),
        "FnDef": (
            traits: [
+                "VisibilityOwner",
                "NameOwner",
                "TypeParamsOwner",
                "AttrsOwner",
@@ -257,6 +258,7 @@ Grammar(
        "RetType": (options: ["TypeRef"]),
        "StructDef": (
            traits: [
+                "VisibilityOwner",
                "NameOwner",
                "TypeParamsOwner",
                "AttrsOwner",
@@ -264,10 +266,11 @@ Grammar(
            ]
        ),
        "NamedFieldDefList": (collections: [["fields", "NamedFieldDef"]]),
-        "NamedFieldDef": ( traits: ["NameOwner", "AttrsOwner"], options: ["TypeRef"] ),
+        "NamedFieldDef": ( traits: ["VisibilityOwner", "NameOwner", "AttrsOwner"], options: ["TypeRef"] ),
        "PosFieldList": (collections: [["fields", "PosField"]]),
-        "PosField": ( traits: ["AttrsOwner"], options: ["TypeRef"]),
+        "PosField": ( traits: ["VisibilityOwner", "AttrsOwner"], options: ["TypeRef"]),
        "EnumDef": ( traits: [
+            "VisibilityOwner",
            "NameOwner",
            "TypeParamsOwner",
            "AttrsOwner",
@@ -275,33 +278,37 @@ Grammar(
        ], options: [["variant_list", "EnumVariantList"]] ),
        "EnumVariantList": ( collections: [["variants", "EnumVariant"]] ),
        "EnumVariant": ( traits: ["NameOwner"], options: ["Expr"] ),
-        "TraitDef": ( traits: ["NameOwner", "AttrsOwner", "DocCommentsOwner"] ),
+        "TraitDef": ( traits: ["VisibilityOwner", "NameOwner", "AttrsOwner", "DocCommentsOwner"] ),
        "Module": (
-            traits: ["NameOwner", "AttrsOwner", "DocCommentsOwner" ],
+            traits: ["VisibilityOwner", "NameOwner", "AttrsOwner", "DocCommentsOwner" ],
            options: [ "ItemList" ]
        ),
        "ItemList": (
+            collections: [["impl_items", "ImplItem"]],
            traits: [ "FnDefOwner", "ModuleItemOwner" ],
        ),
        "ConstDef": ( traits: [
+            "VisibilityOwner",
            "NameOwner",
            "TypeParamsOwner",
            "AttrsOwner",
            "DocCommentsOwner"
        ] ),
        "StaticDef": ( traits: [
+            "VisibilityOwner",
            "NameOwner",
            "TypeParamsOwner",
            "AttrsOwner",
            "DocCommentsOwner"
        ] ),
        "TypeDef": ( traits: [
+            "VisibilityOwner",
            "NameOwner",
            "TypeParamsOwner",
            "AttrsOwner",
            "DocCommentsOwner"
        ] ),
-        "ImplItem": (),
+        "ImplBlock": (options: ["ItemList"]),
        "ParenType": (options: ["TypeRef"]),
        "TupleType": ( collections: [["fields", "TypeRef"]] ),
@@ -342,9 +349,12 @@ Grammar(
            ],
        ),
        "ModuleItem": (
-            enum: ["StructDef", "EnumDef", "FnDef", "TraitDef", "TypeDef", "ImplItem",
+            enum: ["StructDef", "EnumDef", "FnDef", "TraitDef", "TypeDef", "ImplBlock",
                   "UseItem", "ExternCrateItem", "ConstDef", "StaticDef", "Module" ]
        ),
+        "ImplItem": (
+            enum: ["FnDef", "TypeDef", "ConstDef"]
+        ),
        "TupleExpr": (),
        "ArrayExpr": (),
@@ -482,6 +492,7 @@ Grammar(
            ],
        ),
+        "Visibility": (),
        "Name": (),
        "NameRef": (),
        "MacroCall": ( options: [ "TokenTree", "Path" ] ),
@@ -523,7 +534,8 @@ Grammar(
                ["params", "Param"]
            ]
        ),
-        "SelfParam": (),
+        "SelfParam": (options: ["TypeRef", "SelfKw"]),
+        "SelfKw": (),
        "Param": (
            options: [ "Pat", "TypeRef" ],
        ),
diff --git a/crates/ra_syntax/src/grammar/items.rs b/crates/ra_syntax/src/grammar/items.rs
index aa5fe0777..265e84570 100644
--- a/crates/ra_syntax/src/grammar/items.rs
+++ b/crates/ra_syntax/src/grammar/items.rs
@@ -151,8 +151,8 @@ pub(super) fn maybe_item(p: &mut Parser, flavor: ItemFlavor) -> MaybeItem {
        // test unsafe_default_impl
        // unsafe default impl Foo {}
        IMPL_KW => {
-            traits::impl_item(p);
+            traits::impl_block(p);
-            IMPL_ITEM
+            IMPL_BLOCK
        }
        _ => {
            return if has_mods {
diff --git a/crates/ra_syntax/src/grammar/items/traits.rs b/crates/ra_syntax/src/grammar/items/traits.rs
index d4da8b2f7..0a0621753 100644
--- a/crates/ra_syntax/src/grammar/items/traits.rs
+++ b/crates/ra_syntax/src/grammar/items/traits.rs
@@ -40,9 +40,9 @@ pub(crate) fn trait_item_list(p: &mut Parser) {
    m.complete(p, ITEM_LIST);
 }
-// test impl_item
+// test impl_block
 // impl Foo {}
-pub(super) fn impl_item(p: &mut Parser) {
+pub(super) fn impl_block(p: &mut Parser) {
    assert!(p.at(IMPL_KW));
    p.bump();
    if choose_type_params_over_qpath(p) {
@@ -52,7 +52,7 @@ pub(super) fn impl_item(p: &mut Parser) {
    // TODO: never type
    // impl ! {}
-    // test impl_item_neg
+    // test impl_block_neg
    // impl !Send for X {}
    p.eat(EXCL);
    impl_type(p);
diff --git a/crates/ra_syntax/src/parser_api.rs b/crates/ra_syntax/src/parser_api.rs
index 02421def1..3487aef85 100644
--- a/crates/ra_syntax/src/parser_api.rs
+++ b/crates/ra_syntax/src/parser_api.rs
@@ -61,7 +61,7 @@ impl<'t> Parser<'t> {
        Marker::new(self.0.start())
    }
-    /// Advances the parser by one token.
+    /// Advances the parser by one token unconditionally.
    pub(crate) fn bump(&mut self) {
        self.0.bump();
    }
@@ -91,7 +91,7 @@ impl<'t> Parser<'t> {
        self.0.error(message.into())
    }
-    /// Consume the next token if it is `kind`.
+    /// Consume the next token if `kind` matches.
    pub(crate) fn eat(&mut self, kind: SyntaxKind) -> bool {
        if !self.at(kind) {
            return false;
@@ -142,11 +142,13 @@ impl Marker {
        }
    }
-    /// Finishes the syntax tree node and assigns `kind` to it.
+    /// Finishes the syntax tree node and assigns `kind` to it,
+    /// and mark the create a `CompletedMarker` for possible future
+    /// operation like `.precede()` to deal with forward_parent.
    pub(crate) fn complete(mut self, p: &mut Parser, kind: SyntaxKind) -> CompletedMarker {
        self.bomb.defuse();
        p.0.complete(self.pos, kind);
-        CompletedMarker(self.pos, kind)
+        CompletedMarker::new(self.pos, kind)
    }
    /// Abandons the syntax tree node. All its children
@@ -160,13 +162,22 @@ impl Marker {
 pub(crate) struct CompletedMarker(u32, SyntaxKind);
 impl CompletedMarker {
-    /// This one is tricky :-)
+    fn new(pos: u32, kind: SyntaxKind) -> Self {
+        CompletedMarker(pos, kind)
+    }
    /// This method allows to create a new node which starts
    /// *before* the current one. That is, parser could start
    /// node `A`, then complete it, and then after parsing the
    /// whole `A`, decide that it should have started some node
    /// `B` before starting `A`. `precede` allows to do exactly
    /// that. See also docs about `forward_parent` in `Event::Start`.
+    ///
+    /// Given completed events `[START, FINISH]` and its corresponding
+    /// `CompletedMarker(pos: 0, _)`.
+    /// Append a new `START` events as `[START, FINISH, NEWSTART]`,
+    /// then mark `NEWSTART` as `START`'s parent with saving its relative
+    /// distance to `NEWSTART` into forward_parent(=2 in this case);
    pub(crate) fn precede(self, p: &mut Parser) -> Marker {
        Marker::new(p.0.precede(self.0))
    }
diff --git a/crates/ra_syntax/src/parser_impl.rs b/crates/ra_syntax/src/parser_impl.rs
index cb6e370ac..01a51cd8d 100644
--- a/crates/ra_syntax/src/parser_impl.rs
+++ b/crates/ra_syntax/src/parser_impl.rs
@@ -22,10 +22,21 @@ use crate::SyntaxKind::{self, EOF, TOMBSTONE};
 pub(crate) trait Sink {
    type Tree;
+    /// Adds new leaf to the current branch.
    fn leaf(&mut self, kind: SyntaxKind, text: SmolStr);
-    fn start_internal(&mut self, kind: SyntaxKind);
-    fn finish_internal(&mut self);
+    /// Start new branch and make it current.
+    fn start_branch(&mut self, kind: SyntaxKind);
+    /// Finish current branch and restore previous
+    /// branch as current.
+    fn finish_branch(&mut self);
    fn error(&mut self, error: SyntaxError);
+    /// Complete tree building. Make sure that
+    /// `start_branch` and `finish_branch` calls
+    /// are paired!
    fn finish(self) -> Self::Tree;
 }
@@ -52,8 +63,7 @@ pub(crate) fn parse_with<S: Sink>(
 /// to a separate struct in order not to pollute
 /// the public API of the `Parser`.
 pub(crate) struct ParserImpl<'t> {
-    inp: &'t ParserInput<'t>,
+    parser_input: &'t ParserInput<'t>,
    pos: InputPosition,
    events: Vec<Event>,
    steps: Cell<u32>,
@@ -62,8 +72,7 @@ pub(crate) struct ParserImpl<'t> {
 impl<'t> ParserImpl<'t> {
    pub(crate) fn new(inp: &'t ParserInput<'t>) -> ParserImpl<'t> {
        ParserImpl {
-            inp,
+            parser_input: inp,
            pos: InputPosition::new(),
            events: Vec::new(),
            steps: Cell::new(0),
@@ -76,9 +85,11 @@ impl<'t> ParserImpl<'t> {
    }
    pub(super) fn next2(&self) -> Option<(SyntaxKind, SyntaxKind)> {
-        let c1 = self.inp.kind(self.pos);
+        let c1 = self.parser_input.kind(self.pos);
-        let c2 = self.inp.kind(self.pos + 1);
+        let c2 = self.parser_input.kind(self.pos + 1);
-        if self.inp.start(self.pos + 1) == self.inp.start(self.pos) + self.inp.len(self.pos) {
+        if self.parser_input.token_start_at(self.pos + 1)
+            == self.parser_input.token_start_at(self.pos) + self.parser_input.token_len(self.pos)
+        {
            Some((c1, c2))
        } else {
            None
@@ -86,12 +97,14 @@ impl<'t> ParserImpl<'t> {
    }
    pub(super) fn next3(&self) -> Option<(SyntaxKind, SyntaxKind, SyntaxKind)> {
-        let c1 = self.inp.kind(self.pos);
+        let c1 = self.parser_input.kind(self.pos);
-        let c2 = self.inp.kind(self.pos + 1);
+        let c2 = self.parser_input.kind(self.pos + 1);
-        let c3 = self.inp.kind(self.pos + 2);
+        let c3 = self.parser_input.kind(self.pos + 2);
-        if self.inp.start(self.pos + 1) == self.inp.start(self.pos) + self.inp.len(self.pos)
+        if self.parser_input.token_start_at(self.pos + 1)
-            && self.inp.start(self.pos + 2)
+            == self.parser_input.token_start_at(self.pos) + self.parser_input.token_len(self.pos)
-                == self.inp.start(self.pos + 1) + self.inp.len(self.pos + 1)
+            && self.parser_input.token_start_at(self.pos + 2)
+                == self.parser_input.token_start_at(self.pos + 1)
+                    + self.parser_input.token_len(self.pos + 1)
        {
            Some((c1, c2, c3))
        } else {
@@ -99,29 +112,27 @@ impl<'t> ParserImpl<'t> {
        }
    }
+    /// Get the syntax kind of the nth token.
    pub(super) fn nth(&self, n: u32) -> SyntaxKind {
        let steps = self.steps.get();
-        if steps > 10_000_000 {
+        assert!(steps <= 10_000_000, "the parser seems stuck");
-            panic!("the parser seems stuck");
-        }
        self.steps.set(steps + 1);
-        self.inp.kind(self.pos + n)
+        self.parser_input.kind(self.pos + n)
    }
    pub(super) fn at_kw(&self, t: &str) -> bool {
-        self.inp.text(self.pos) == t
+        self.parser_input.token_text(self.pos) == t
    }
+    /// Start parsing right behind the last event.
    pub(super) fn start(&mut self) -> u32 {
        let pos = self.events.len() as u32;
-        self.event(Event::Start {
+        self.push_event(Event::tombstone());
-            kind: TOMBSTONE,
-            forward_parent: None,
-        });
        pos
    }
+    /// Advances the parser by one token unconditionally.
    pub(super) fn bump(&mut self) {
        let kind = self.nth(0);
        if kind == EOF {
@@ -144,15 +155,17 @@ impl<'t> ParserImpl<'t> {
    fn do_bump(&mut self, kind: SyntaxKind, n_raw_tokens: u8) {
        self.pos += u32::from(n_raw_tokens);
-        self.event(Event::Token { kind, n_raw_tokens });
+        self.push_event(Event::Token { kind, n_raw_tokens });
    }
+    /// Append one Error event to the back of events.
    pub(super) fn error(&mut self, msg: String) {
-        self.event(Event::Error {
+        self.push_event(Event::Error {
            msg: ParseError(msg),
        })
    }
+    /// Complete an event with appending a `Finish` event.
    pub(super) fn complete(&mut self, pos: u32, kind: SyntaxKind) {
        match self.events[pos as usize] {
            Event::Start {
@@ -162,9 +175,10 @@ impl<'t> ParserImpl<'t> {
            }
            _ => unreachable!(),
        }
-        self.event(Event::Finish);
+        self.push_event(Event::Finish);
    }
+    /// Ignore the dummy `Start` event.
    pub(super) fn abandon(&mut self, pos: u32) {
        let idx = pos as usize;
        if idx == self.events.len() - 1 {
@@ -178,6 +192,7 @@ impl<'t> ParserImpl<'t> {
        }
    }
+    /// Save the relative distance of a completed event to its forward_parent.
    pub(super) fn precede(&mut self, pos: u32) -> u32 {
        let new_pos = self.start();
        match self.events[pos as usize] {
@@ -192,7 +207,7 @@ impl<'t> ParserImpl<'t> {
        new_pos
    }
-    fn event(&mut self, event: Event) {
+    fn push_event(&mut self, event: Event) {
        self.events.push(event)
    }
 }
diff --git a/crates/ra_syntax/src/parser_impl/event.rs b/crates/ra_syntax/src/parser_impl/event.rs
index 3d8b062d5..73dd6e02b 100644
--- a/crates/ra_syntax/src/parser_impl/event.rs
+++ b/crates/ra_syntax/src/parser_impl/event.rs
@@ -36,7 +36,7 @@ pub(crate) enum Event {
    ///
    /// For left-recursive syntactic constructs, the parser produces
    /// a child node before it sees a parent. `forward_parent`
-    /// exists to allow to tweak parent-child relationships.
+    /// saves the position of current event's parent.
    ///
    /// Consider this path
    ///
@@ -84,6 +84,15 @@ pub(crate) enum Event {
    },
 }
+impl Event {
+    pub(crate) fn tombstone() -> Self {
+        Event::Start {
+            kind: TOMBSTONE,
+            forward_parent: None,
+        }
+    }
+}
 pub(super) struct EventProcessor<'a, S: Sink> {
    sink: S,
    text_pos: TextUnit,
@@ -110,17 +119,12 @@ impl<'a, S: Sink> EventProcessor<'a, S> {
        }
    }
+    /// Generate the syntax tree with the control of events.
    pub(super) fn process(mut self) -> S {
-        fn tombstone() -> Event {
-            Event::Start {
-                kind: TOMBSTONE,
-                forward_parent: None,
-            }
-        }
        let mut forward_parents = Vec::new();
        for i in 0..self.events.len() {
-            match mem::replace(&mut self.events[i], tombstone()) {
+            match mem::replace(&mut self.events[i], Event::tombstone()) {
                Event::Start {
                    kind: TOMBSTONE, ..
                } => (),
@@ -129,12 +133,18 @@ impl<'a, S: Sink> EventProcessor<'a, S> {
                    kind,
                    forward_parent,
                } => {
+                    // For events[A, B, C], B is A's forward_parent, C is B's forward_parent,
+                    // in the normal control flow, the parent-child relation: `A -> B -> C`,
+                    // while with the magic forward_parent, it writes: `C <- B <- A`.
+                    // append `A` into parents.
                    forward_parents.push(kind);
                    let mut idx = i;
                    let mut fp = forward_parent;
                    while let Some(fwd) = fp {
                        idx += fwd as usize;
-                        fp = match mem::replace(&mut self.events[idx], tombstone()) {
+                        // append `A`'s forward_parent `B`
+                        fp = match mem::replace(&mut self.events[idx], Event::tombstone()) {
                            Event::Start {
                                kind,
                                forward_parent,
@@ -144,17 +154,19 @@ impl<'a, S: Sink> EventProcessor<'a, S> {
                            }
                            _ => unreachable!(),
                        };
+                        // append `B`'s forward_parent `C` in the next stage.
                    }
                    for kind in forward_parents.drain(..).rev() {
                        self.start(kind);
                    }
                }
                Event::Finish => {
-                    let last = i == self.events.len() - 1;
+                    let is_last = i == self.events.len() - 1;
-                    self.finish(last);
+                    self.finish(is_last);
                }
                Event::Token { kind, n_raw_tokens } => {
-                    self.eat_ws();
+                    self.eat_trivias();
                    let n_raw_tokens = n_raw_tokens as usize;
                    let len = self.tokens[self.token_pos..self.token_pos + n_raw_tokens]
                        .iter()
@@ -171,9 +183,10 @@ impl<'a, S: Sink> EventProcessor<'a, S> {
        self.sink
    }
+    /// Add the node into syntax tree but discard the comments/whitespaces.
    fn start(&mut self, kind: SyntaxKind) {
        if kind == SOURCE_FILE {
-            self.sink.start_internal(kind);
+            self.sink.start_branch(kind);
            return;
        }
        let n_trivias = self.tokens[self.token_pos..]
@@ -194,18 +207,18 @@ impl<'a, S: Sink> EventProcessor<'a, S> {
            n_attached_trivias(kind, leading_trivias)
        };
        self.eat_n_trivias(n_trivias - n_attached_trivias);
-        self.sink.start_internal(kind);
+        self.sink.start_branch(kind);
        self.eat_n_trivias(n_attached_trivias);
    }
-    fn finish(&mut self, last: bool) {
+    fn finish(&mut self, is_last: bool) {
-        if last {
+        if is_last {
-            self.eat_ws()
+            self.eat_trivias()
        }
-        self.sink.finish_internal();
+        self.sink.finish_branch();
    }
-    fn eat_ws(&mut self) {
+    fn eat_trivias(&mut self) {
        while let Some(&token) = self.tokens.get(self.token_pos) {
            if !token.kind.is_trivia() {
                break;
@@ -236,7 +249,7 @@ fn n_attached_trivias<'a>(
    trivias: impl Iterator<Item = (SyntaxKind, &'a str)>,
 ) -> usize {
    match kind {
-        STRUCT_DEF | ENUM_DEF | FN_DEF | TRAIT_DEF | MODULE => {
+        CONST_DEF | TYPE_DEF | STRUCT_DEF | ENUM_DEF | FN_DEF | TRAIT_DEF | MODULE => {
            let mut res = 0;
            for (i, (kind, text)) in trivias.enumerate() {
                match kind {
diff --git a/crates/ra_syntax/src/parser_impl/input.rs b/crates/ra_syntax/src/parser_impl/input.rs
index ac6d900d8..7fde5b3ab 100644
--- a/crates/ra_syntax/src/parser_impl/input.rs
+++ b/crates/ra_syntax/src/parser_impl/input.rs
@@ -4,11 +4,26 @@ use std::ops::{Add, AddAssign};
 pub(crate) struct ParserInput<'t> {
    text: &'t str,
+    /// start position of each token(expect whitespace and comment)
+    /// ```non-rust
+    ///  struct Foo;
+    /// ^------^---
+    /// |      |  ^-
+    /// 0      7  10
+    /// ```
+    /// (token, start_offset): `[(struct, 0), (Foo, 7), (;, 10)]`
    start_offsets: Vec<TextUnit>,
-    tokens: Vec<Token>, // non-whitespace tokens
+    /// non-whitespace/comment tokens
+    /// ```non-rust
+    /// struct Foo {}
+    /// ^^^^^^ ^^^ ^^
+    /// ```
+    /// tokens: `[struct, Foo, {, }]`
+    tokens: Vec<Token>,
 }
 impl<'t> ParserInput<'t> {
+    /// Generate input from tokens(expect comment and whitespace).
    pub fn new(text: &'t str, raw_tokens: &'t [Token]) -> ParserInput<'t> {
        let mut tokens = Vec::new();
        let mut start_offsets = Vec::new();
@@ -28,6 +43,7 @@ impl<'t> ParserInput<'t> {
        }
    }
+    /// Get the syntax kind of token at given input position.
    pub fn kind(&self, pos: InputPosition) -> SyntaxKind {
        let idx = pos.0 as usize;
        if !(idx < self.tokens.len()) {
@@ -36,7 +52,8 @@ impl<'t> ParserInput<'t> {
        self.tokens[idx].kind
    }
-    pub fn len(&self, pos: InputPosition) -> TextUnit {
+    /// Get the length of a token at given input position.
+    pub fn token_len(&self, pos: InputPosition) -> TextUnit {
        let idx = pos.0 as usize;
        if !(idx < self.tokens.len()) {
            return 0.into();
@@ -44,7 +61,8 @@ impl<'t> ParserInput<'t> {
        self.tokens[idx].len
    }
-    pub fn start(&self, pos: InputPosition) -> TextUnit {
+    /// Get the start position of a taken at given input position.
+    pub fn token_start_at(&self, pos: InputPosition) -> TextUnit {
        let idx = pos.0 as usize;
        if !(idx < self.tokens.len()) {
            return 0.into();
@@ -52,7 +70,8 @@ impl<'t> ParserInput<'t> {
        self.start_offsets[idx]
    }
-    pub fn text(&self, pos: InputPosition) -> &'t str {
+    /// Get the raw text of a token at given input position.
+    pub fn token_text(&self, pos: InputPosition) -> &'t str {
        let idx = pos.0 as usize;
        if !(idx < self.tokens.len()) {
            return "";
diff --git a/crates/ra_syntax/src/reparsing.rs b/crates/ra_syntax/src/reparsing.rs
index 208cae5c8..7ee71a1b6 100644
--- a/crates/ra_syntax/src/reparsing.rs
+++ b/crates/ra_syntax/src/reparsing.rs
@@ -100,7 +100,7 @@ fn find_reparsable_node(
            ITEM_LIST => {
                let parent = node.parent().unwrap();
                match parent.kind() {
-                    IMPL_ITEM => grammar::impl_item_list,
+                    IMPL_BLOCK => grammar::impl_item_list,
                    TRAIT_DEF => grammar::trait_item_list,
                    MODULE => grammar::mod_item_list,
                    _ => return None,
diff --git a/crates/ra_syntax/src/syntax_kinds/generated.rs b/crates/ra_syntax/src/syntax_kinds/generated.rs
index 3a869ad34..ef4588d93 100644
--- a/crates/ra_syntax/src/syntax_kinds/generated.rs
+++ b/crates/ra_syntax/src/syntax_kinds/generated.rs
@@ -128,7 +128,7 @@ pub enum SyntaxKind {
    STATIC_DEF,
    CONST_DEF,
    TRAIT_DEF,
-    IMPL_ITEM,
+    IMPL_BLOCK,
    TYPE_DEF,
    MACRO_CALL,
    TOKEN_TREE,
@@ -389,7 +389,7 @@ impl SyntaxKind {
            STATIC_DEF => &SyntaxInfo { name: "STATIC_DEF" },
            CONST_DEF => &SyntaxInfo { name: "CONST_DEF" },
            TRAIT_DEF => &SyntaxInfo { name: "TRAIT_DEF" },
-            IMPL_ITEM => &SyntaxInfo { name: "IMPL_ITEM" },
+            IMPL_BLOCK => &SyntaxInfo { name: "IMPL_BLOCK" },
            TYPE_DEF => &SyntaxInfo { name: "TYPE_DEF" },
            MACRO_CALL => &SyntaxInfo { name: "MACRO_CALL" },
            TOKEN_TREE => &SyntaxInfo { name: "TOKEN_TREE" },
diff --git a/crates/ra_syntax/src/yellow/builder.rs b/crates/ra_syntax/src/yellow/builder.rs
index 9fcebfb93..37ae6329b 100644
--- a/crates/ra_syntax/src/yellow/builder.rs
+++ b/crates/ra_syntax/src/yellow/builder.rs
@@ -26,11 +26,11 @@ impl Sink for GreenBuilder {
        self.inner.leaf(kind, text);
    }
-    fn start_internal(&mut self, kind: SyntaxKind) {
+    fn start_branch(&mut self, kind: SyntaxKind) {
        self.inner.start_internal(kind)
    }
-    fn finish_internal(&mut self) {
+    fn finish_branch(&mut self) {
        self.inner.finish_internal();
    }
diff --git a/crates/ra_syntax/src/yellow/syntax_text.rs b/crates/ra_syntax/src/yellow/syntax_text.rs
index 46bde9a08..279a83b61 100644
--- a/crates/ra_syntax/src/yellow/syntax_text.rs
+++ b/crates/ra_syntax/src/yellow/syntax_text.rs
@@ -119,3 +119,27 @@ impl SyntaxTextSlice for ops::Range<TextUnit> {
        TextRange::from_to(self.start, self.end).restrict(range)
    }
 }
+impl From<SyntaxText<'_>> for String {
+    fn from(text: SyntaxText) -> String {
+        text.to_string()
+    }
+}
+impl PartialEq<str> for SyntaxText<'_> {
+    fn eq(&self, mut rhs: &str) -> bool {
+        for chunk in self.chunks() {
+            if !rhs.starts_with(chunk) {
+                return false;
+            }
+            rhs = &rhs[chunk.len()..];
+        }
+        rhs.is_empty()
+    }
+}
+impl PartialEq<&'_ str> for SyntaxText<'_> {
+    fn eq(&self, rhs: &&str) -> bool {
+        self == *rhs
+    }
+}
diff --git a/crates/ra_syntax/tests/data/parser/err/0018_incomplete_fn.txt b/crates/ra_syntax/tests/data/parser/err/0018_incomplete_fn.txt
index 3937be255..262cbba1e 100644
--- a/crates/ra_syntax/tests/data/parser/err/0018_incomplete_fn.txt
+++ b/crates/ra_syntax/tests/data/parser/err/0018_incomplete_fn.txt
@@ -1,5 +1,5 @@
 SOURCE_FILE@[0; 183)
-  IMPL_ITEM@[0; 182)
+  IMPL_BLOCK@[0; 182)
    IMPL_KW@[0; 4)
    WHITESPACE@[4; 5)
    PATH_TYPE@[5; 13)
diff --git a/crates/ra_syntax/tests/data/parser/err/0022_bad_exprs.txt b/crates/ra_syntax/tests/data/parser/err/0022_bad_exprs.txt
index 55999c160..da3894133 100644
--- a/crates/ra_syntax/tests/data/parser/err/0022_bad_exprs.txt
+++ b/crates/ra_syntax/tests/data/parser/err/0022_bad_exprs.txt
@@ -94,7 +94,7 @@ SOURCE_FILE@[0; 112)
          COMMA@[54; 55)
          err: `expected SEMI`
      WHITESPACE@[55; 56)
-      IMPL_ITEM@[56; 60)
+      IMPL_BLOCK@[56; 60)
        IMPL_KW@[56; 60)
        err: `expected type`
        err: `expected `{``
diff --git a/crates/ra_syntax/tests/data/parser/err/0026_imp_recovery.txt b/crates/ra_syntax/tests/data/parser/err/0026_imp_recovery.txt
index 82683f6ee..9b5fadcf7 100644
--- a/crates/ra_syntax/tests/data/parser/err/0026_imp_recovery.txt
+++ b/crates/ra_syntax/tests/data/parser/err/0026_imp_recovery.txt
@@ -1,5 +1,5 @@
 SOURCE_FILE@[0; 38)
-  IMPL_ITEM@[0; 14)
+  IMPL_BLOCK@[0; 14)
    IMPL_KW@[0; 4)
    TYPE_PARAM_LIST@[4; 14)
      L_ANGLE@[4; 5)
@@ -17,7 +17,7 @@ SOURCE_FILE@[0; 38)
      err: `expected trait or type`
      err: `expected `{``
  WHITESPACE@[14; 15)
-  IMPL_ITEM@[15; 37)
+  IMPL_BLOCK@[15; 37)
    IMPL_KW@[15; 19)
    TYPE_PARAM_LIST@[19; 22)
      L_ANGLE@[19; 20)
diff --git a/crates/ra_syntax/tests/data/parser/inline/err/0002_misplaced_label_err.txt b/crates/ra_syntax/tests/data/parser/inline/err/0002_misplaced_label_err.txt
index 75533ecc1..8021aee00 100644
--- a/crates/ra_syntax/tests/data/parser/inline/err/0002_misplaced_label_err.txt
+++ b/crates/ra_syntax/tests/data/parser/inline/err/0002_misplaced_label_err.txt
@@ -19,7 +19,7 @@ SOURCE_FILE@[0; 30)
            err: `expected a loop`
            err: `expected SEMI`
      WHITESPACE@[22; 23)
-      IMPL_ITEM@[23; 27)
+      IMPL_BLOCK@[23; 27)
        IMPL_KW@[23; 27)
        err: `expected type`
        err: `expected `{``
diff --git a/crates/ra_syntax/tests/data/parser/inline/err/0004_impl_type.txt b/crates/ra_syntax/tests/data/parser/inline/err/0004_impl_type.txt
index 7279d5cae..6875ed016 100644
--- a/crates/ra_syntax/tests/data/parser/inline/err/0004_impl_type.txt
+++ b/crates/ra_syntax/tests/data/parser/inline/err/0004_impl_type.txt
@@ -1,5 +1,5 @@
 SOURCE_FILE@[0; 87)
-  IMPL_ITEM@[0; 12)
+  IMPL_BLOCK@[0; 12)
    IMPL_KW@[0; 4)
    WHITESPACE@[4; 5)
    PATH_TYPE@[5; 9)
@@ -12,7 +12,7 @@ SOURCE_FILE@[0; 87)
      L_CURLY@[10; 11)
      R_CURLY@[11; 12)
  WHITESPACE@[12; 13)
-  IMPL_ITEM@[13; 33)
+  IMPL_BLOCK@[13; 33)
    IMPL_KW@[13; 17)
    WHITESPACE@[17; 18)
    PATH_TYPE@[18; 24)
@@ -33,12 +33,12 @@ SOURCE_FILE@[0; 87)
      L_CURLY@[31; 32)
      R_CURLY@[32; 33)
  WHITESPACE@[33; 34)
-  IMPL_ITEM@[34; 38)
+  IMPL_BLOCK@[34; 38)
    IMPL_KW@[34; 38)
    err: `expected trait or type`
    err: `expected `{``
  WHITESPACE@[38; 39)
-  IMPL_ITEM@[39; 54)
+  IMPL_BLOCK@[39; 54)
    IMPL_KW@[39; 43)
    WHITESPACE@[43; 44)
    PATH_TYPE@[44; 51)
@@ -51,7 +51,7 @@ SOURCE_FILE@[0; 87)
      L_CURLY@[52; 53)
      R_CURLY@[53; 54)
  WHITESPACE@[54; 55)
-  IMPL_ITEM@[55; 70)
+  IMPL_BLOCK@[55; 70)
    IMPL_KW@[55; 59)
    WHITESPACE@[59; 60)
    PATH_TYPE@[60; 66)
@@ -64,7 +64,7 @@ SOURCE_FILE@[0; 87)
    err: `expected trait or type`
    err: `expected `{``
  WHITESPACE@[70; 71)
-  IMPL_ITEM@[71; 86)
+  IMPL_BLOCK@[71; 86)
    IMPL_KW@[71; 75)
    WHITESPACE@[75; 76)
    PATH_TYPE@[76; 83)
diff --git a/crates/ra_syntax/tests/data/parser/inline/ok/0001_trait_item_list.txt b/crates/ra_syntax/tests/data/parser/inline/ok/0001_trait_item_list.txt
index 998ac3da9..de7df7312 100644
--- a/crates/ra_syntax/tests/data/parser/inline/ok/0001_trait_item_list.txt
+++ b/crates/ra_syntax/tests/data/parser/inline/ok/0001_trait_item_list.txt
@@ -1,5 +1,5 @@
 SOURCE_FILE@[0; 83)
-  IMPL_ITEM@[0; 82)
+  IMPL_BLOCK@[0; 82)
    IMPL_KW@[0; 4)
    WHITESPACE@[4; 5)
    PATH_TYPE@[5; 6)
diff --git a/crates/ra_syntax/tests/data/parser/inline/ok/0006_self_param.txt b/crates/ra_syntax/tests/data/parser/inline/ok/0006_self_param.txt
index 53027c852..4df01c6e5 100644
--- a/crates/ra_syntax/tests/data/parser/inline/ok/0006_self_param.txt
+++ b/crates/ra_syntax/tests/data/parser/inline/ok/0006_self_param.txt
@@ -1,5 +1,5 @@
 SOURCE_FILE@[0; 128)
-  IMPL_ITEM@[0; 127)
+  IMPL_BLOCK@[0; 127)
    IMPL_KW@[0; 4)
    WHITESPACE@[4; 5)
    PATH_TYPE@[5; 6)
diff --git a/crates/ra_syntax/tests/data/parser/inline/ok/0018_arb_self_types.txt b/crates/ra_syntax/tests/data/parser/inline/ok/0018_arb_self_types.txt
index b2f04ea7b..03139f7a4 100644
--- a/crates/ra_syntax/tests/data/parser/inline/ok/0018_arb_self_types.txt
+++ b/crates/ra_syntax/tests/data/parser/inline/ok/0018_arb_self_types.txt
@@ -1,5 +1,5 @@
 SOURCE_FILE@[0; 69)
-  IMPL_ITEM@[0; 68)
+  IMPL_BLOCK@[0; 68)
    IMPL_KW@[0; 4)
    WHITESPACE@[4; 5)
    PATH_TYPE@[5; 6)
diff --git a/crates/ra_syntax/tests/data/parser/inline/ok/0021_impl_item_list.txt b/crates/ra_syntax/tests/data/parser/inline/ok/0021_impl_item_list.txt
index b15f93cd2..50426bdfe 100644
--- a/crates/ra_syntax/tests/data/parser/inline/ok/0021_impl_item_list.txt
+++ b/crates/ra_syntax/tests/data/parser/inline/ok/0021_impl_item_list.txt
@@ -1,5 +1,5 @@
 SOURCE_FILE@[0; 89)
-  IMPL_ITEM@[0; 88)
+  IMPL_BLOCK@[0; 88)
    IMPL_KW@[0; 4)
    WHITESPACE@[4; 5)
    PATH_TYPE@[5; 6)
diff --git a/crates/ra_syntax/tests/data/parser/inline/ok/0047_unsafe_default_impl.txt b/crates/ra_syntax/tests/data/parser/inline/ok/0047_unsafe_default_impl.txt
index 6003ba645..5d68e88d6 100644
--- a/crates/ra_syntax/tests/data/parser/inline/ok/0047_unsafe_default_impl.txt
+++ b/crates/ra_syntax/tests/data/parser/inline/ok/0047_unsafe_default_impl.txt
@@ -1,5 +1,5 @@
 SOURCE_FILE@[0; 27)
-  IMPL_ITEM@[0; 26)
+  IMPL_BLOCK@[0; 26)
    UNSAFE_KW@[0; 6)
    WHITESPACE@[6; 7)
    DEFAULT_KW@[7; 14)
diff --git a/crates/ra_syntax/tests/data/parser/inline/ok/0063_impl_item_neg.rs b/crates/ra_syntax/tests/data/parser/inline/ok/0063_impl_block_neg.rs
index b7527c870..b7527c870 100644
--- a/crates/ra_syntax/tests/data/parser/inline/ok/0063_impl_item_neg.rs
+++ b/crates/ra_syntax/tests/data/parser/inline/ok/0063_impl_block_neg.rs
diff --git a/crates/ra_syntax/tests/data/parser/inline/ok/0063_impl_item_neg.txt b/crates/ra_syntax/tests/data/parser/inline/ok/0063_impl_block_neg.txt
index b83db380e..563e43508 100644
--- a/crates/ra_syntax/tests/data/parser/inline/ok/0063_impl_item_neg.txt
+++ b/crates/ra_syntax/tests/data/parser/inline/ok/0063_impl_block_neg.txt
@@ -1,5 +1,5 @@
 SOURCE_FILE@[0; 20)
-  IMPL_ITEM@[0; 19)
+  IMPL_BLOCK@[0; 19)
    IMPL_KW@[0; 4)
    WHITESPACE@[4; 5)
    EXCL@[5; 6)
diff --git a/crates/ra_syntax/tests/data/parser/inline/ok/0079_impl_item.rs b/crates/ra_syntax/tests/data/parser/inline/ok/0079_impl_block.rs
index d6337f6b3..d6337f6b3 100644
--- a/crates/ra_syntax/tests/data/parser/inline/ok/0079_impl_item.rs
+++ b/crates/ra_syntax/tests/data/parser/inline/ok/0079_impl_block.rs
diff --git a/crates/ra_syntax/tests/data/parser/inline/ok/0079_impl_item.txt b/crates/ra_syntax/tests/data/parser/inline/ok/0079_impl_block.txt
index 1b9a8aa0e..a2c218aa9 100644
--- a/crates/ra_syntax/tests/data/parser/inline/ok/0079_impl_item.txt
+++ b/crates/ra_syntax/tests/data/parser/inline/ok/0079_impl_block.txt
@@ -1,5 +1,5 @@
 SOURCE_FILE@[0; 12)
-  IMPL_ITEM@[0; 11)
+  IMPL_BLOCK@[0; 11)
    IMPL_KW@[0; 4)
    WHITESPACE@[4; 5)
    PATH_TYPE@[5; 8)
diff --git a/crates/ra_syntax/tests/data/parser/inline/ok/0087_unsafe_impl.txt b/crates/ra_syntax/tests/data/parser/inline/ok/0087_unsafe_impl.txt
index f9c96c242..d93c0df4d 100644
--- a/crates/ra_syntax/tests/data/parser/inline/ok/0087_unsafe_impl.txt
+++ b/crates/ra_syntax/tests/data/parser/inline/ok/0087_unsafe_impl.txt
@@ -1,5 +1,5 @@
 SOURCE_FILE@[0; 19)
-  IMPL_ITEM@[0; 18)
+  IMPL_BLOCK@[0; 18)
    UNSAFE_KW@[0; 6)
    WHITESPACE@[6; 7)
    IMPL_KW@[7; 11)
diff --git a/crates/ra_syntax/tests/data/parser/inline/ok/0097_default_impl.txt b/crates/ra_syntax/tests/data/parser/inline/ok/0097_default_impl.txt
index f45b6251f..0b9af800b 100644
--- a/crates/ra_syntax/tests/data/parser/inline/ok/0097_default_impl.txt
+++ b/crates/ra_syntax/tests/data/parser/inline/ok/0097_default_impl.txt
@@ -1,5 +1,5 @@
 SOURCE_FILE@[0; 20)
-  IMPL_ITEM@[0; 19)
+  IMPL_BLOCK@[0; 19)
    DEFAULT_KW@[0; 7)
    WHITESPACE@[7; 8)
    IMPL_KW@[8; 12)
diff --git a/crates/ra_syntax/tests/data/parser/ok/0037_mod.rs b/crates/ra_syntax/tests/data/parser/ok/0037_mod.rs
new file mode 100644
index 000000000..7e5a1b835
--- /dev/null
+++ b/crates/ra_syntax/tests/data/parser/ok/0037_mod.rs
@@ -0,0 +1,5 @@
+// https://github.com/rust-analyzer/rust-analyzer/issues/357
+//! docs
+// non-docs
+mod foo {}
+\ No newline at end of file
diff --git a/crates/ra_syntax/tests/data/parser/ok/0037_mod.txt b/crates/ra_syntax/tests/data/parser/ok/0037_mod.txt
new file mode 100644
index 000000000..f8a20ac53
--- /dev/null
+++ b/crates/ra_syntax/tests/data/parser/ok/0037_mod.txt
@@ -0,0 +1,16 @@
+SOURCE_FILE@[0; 93)
+  COMMENT@[0; 60)
+  WHITESPACE@[60; 62)
+  MODULE@[62; 93)
+    COMMENT@[62; 70)
+    WHITESPACE@[70; 71)
+    COMMENT@[71; 82)
+    WHITESPACE@[82; 83)
+    MOD_KW@[83; 86)
+    WHITESPACE@[86; 87)
+    NAME@[87; 90)
+      IDENT@[87; 90) "foo"
+    WHITESPACE@[90; 91)
+    ITEM_LIST@[91; 93)
+      L_CURLY@[91; 92)
+      R_CURLY@[92; 93)