13 files changed, 385 insertions, 95 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> {
-    fn eq(&self, other: &ImplItemNode<R1>) -> bool { self.syntax == other.syntax }
+impl<R1: TreeRoot<RaTypes>, R2: TreeRoot<RaTypes>> PartialEq<ImplBlockNode<R1>> for ImplBlockNode<R2> {
+    fn eq(&self, other: &ImplBlockNode<R1>) -> bool { self.syntax == other.syntax }
 }
-impl<R: TreeRoot<RaTypes>> Eq for ImplItemNode<R> {}
-impl<R: TreeRoot<RaTypes>> Hash for ImplItemNode<R> {
+impl<R: TreeRoot<RaTypes>> Eq for ImplBlockNode<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> {
-    pub fn borrowed(&self) -> ImplItem {
-        ImplItemNode { syntax: self.syntax.borrowed() }
+impl<R: TreeRoot<RaTypes>> ImplBlockNode<R> {
+    pub fn borrowed(&self) -> ImplBlock {
+        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);
-            IMPL_ITEM
+            traits::impl_block(p);
+            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 c2 = self.inp.kind(self.pos + 1);
-        if self.inp.start(self.pos + 1) == self.inp.start(self.pos) + self.inp.len(self.pos) {
+        let c1 = self.parser_input.kind(self.pos);
+        let c2 = self.parser_input.kind(self.pos + 1);
+        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 c2 = self.inp.kind(self.pos + 1);
-        let c3 = self.inp.kind(self.pos + 2);
-        if self.inp.start(self.pos + 1) == self.inp.start(self.pos) + self.inp.len(self.pos)
-            && self.inp.start(self.pos + 2)
-                == self.inp.start(self.pos + 1) + self.inp.len(self.pos + 1)
+        let c1 = self.parser_input.kind(self.pos);
+        let c2 = self.parser_input.kind(self.pos + 1);
+        let c3 = self.parser_input.kind(self.pos + 2);
+        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)
+            && 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 {
-            panic!("the parser seems stuck");
-        }
+        assert!(steps <= 10_000_000, "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 {
-            kind: TOMBSTONE,
-            forward_parent: None,
-        });
+        self.push_event(Event::tombstone());
         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;
-                    self.finish(last);
+                    let is_last = i == self.events.len() - 1;
+                    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) {
-        if last {
-            self.eat_ws()
+    fn finish(&mut self, is_last: bool) {
+        if is_last {
+            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
+    }
+}