4 files changed, 51 insertions, 12 deletions

diff --git a/crates/ra_syntax/src/ast.rs b/crates/ra_syntax/src/ast.rs
index 1b2ce921a..a12da5be2 100644
--- a/crates/ra_syntax/src/ast.rs
+++ b/crates/ra_syntax/src/ast.rs
@@ -173,7 +173,7 @@ fn test_doc_comment_single_line_block_strips_suffix_whitespace() {
     .ok()
     .unwrap();
     let module = file.syntax().descendants().find_map(Module::cast).unwrap();
-    assert_eq!("this is mod foo", module.doc_comment_text().unwrap());
+    assert_eq!("this is mod foo ", module.doc_comment_text().unwrap());
 }
 
 #[test]
@@ -191,7 +191,27 @@ fn test_doc_comment_multi_line_block_strips_suffix() {
     .ok()
     .unwrap();
     let module = file.syntax().descendants().find_map(Module::cast).unwrap();
-    assert_eq!("        this\n        is\n        mod foo", module.doc_comment_text().unwrap());
+    assert_eq!(
+        "        this\n        is\n        mod foo\n        ",
+        module.doc_comment_text().unwrap()
+    );
+}
+
+#[test]
+fn test_comments_preserve_trailing_whitespace() {
+    let file = SourceFile::parse(
+        r#"
+/// Representation of a Realm.   
+/// In the specification these are called Realm Records.
+struct Realm {}"#,
+    )
+    .ok()
+    .unwrap();
+    let def = file.syntax().descendants().find_map(StructDef::cast).unwrap();
+    assert_eq!(
+        "Representation of a Realm.   \nIn the specification these are called Realm Records.",
+        def.doc_comment_text().unwrap()
+    );
 }
 
 #[test]
diff --git a/crates/ra_syntax/src/ast/make.rs b/crates/ra_syntax/src/ast/make.rs
index 00422ea91..3d5f18bfa 100644
--- a/crates/ra_syntax/src/ast/make.rs
+++ b/crates/ra_syntax/src/ast/make.rs
@@ -77,7 +77,7 @@ pub fn tuple_struct_pat(
 
 pub fn record_pat(path: ast::Path, pats: impl Iterator<Item = ast::Pat>) -> ast::RecordPat {
     let pats_str = pats.map(|p| p.syntax().to_string()).join(", ");
-    return from_text(&format!("{}{{ {} }}", path.syntax(), pats_str));
+    return from_text(&format!("{} {{ {} }}", path.syntax(), pats_str));
 
     fn from_text(text: &str) -> ast::RecordPat {
         ast_from_text(&format!("fn f({}: ())", text))
@@ -129,11 +129,11 @@ pub fn where_clause(preds: impl Iterator<Item = ast::WherePred>) -> ast::WhereCl
 }
 
 pub fn if_expression(condition: &ast::Expr, statement: &str) -> ast::IfExpr {
-    return ast_from_text(&format!(
+    ast_from_text(&format!(
         "fn f() {{ if !{} {{\n    {}\n}}\n}}",
         condition.syntax().text(),
         statement
-    ));
+    ))
 }
 
 fn ast_from_text<N: AstNode>(text: &str) -> N {
diff --git a/crates/ra_syntax/src/ast/traits.rs b/crates/ra_syntax/src/ast/traits.rs
index f275a4955..c2b005886 100644
--- a/crates/ra_syntax/src/ast/traits.rs
+++ b/crates/ra_syntax/src/ast/traits.rs
@@ -6,6 +6,7 @@ use itertools::Itertools;
 
 use crate::{
     ast::{self, child_opt, children, AstChildren, AstNode, AstToken},
+    match_ast,
     syntax_node::{SyntaxElementChildren, SyntaxNodeChildren},
 };
 
@@ -68,11 +69,12 @@ impl Iterator for ItemOrMacroIter {
     fn next(&mut self) -> Option<ItemOrMacro> {
         loop {
             let n = self.0.next()?;
-            if let Some(item) = ast::ModuleItem::cast(n.clone()) {
-                return Some(ItemOrMacro::Item(item));
-            }
-            if let Some(call) = ast::MacroCall::cast(n) {
-                return Some(ItemOrMacro::Macro(call));
+            match_ast! {
+                match n {
+                    ast::ModuleItem(it) => { return Some(ItemOrMacro::Item(it)) },
+                    ast::MacroCall(it) => { return Some(ItemOrMacro::Macro(it)) },
+                    _ => {},
+                }
             }
         }
     }
@@ -120,7 +122,7 @@ pub trait DocCommentsOwner: AstNode {
                 has_comments = true;
                 let prefix_len = comment.prefix().len();
 
-                let line = comment.text().as_str();
+                let line: &str = comment.text().as_str();
 
                 // Determine if the prefix or prefix + 1 char is stripped
                 let pos =
@@ -136,7 +138,10 @@ pub trait DocCommentsOwner: AstNode {
                     line.len()
                 };
 
-                line[pos..end].trim_end().to_owned()
+                // Note that we do not trim the end of the line here
+                // since whitespace can have special meaning at the end
+                // of a line in markdown.
+                line[pos..end].to_owned()
             })
             .join("\n");
 
diff --git a/crates/ra_syntax/src/lib.rs b/crates/ra_syntax/src/lib.rs
index c315ba552..5dcb6a95a 100644
--- a/crates/ra_syntax/src/lib.rs
+++ b/crates/ra_syntax/src/lib.rs
@@ -160,6 +160,20 @@ impl SourceFile {
     }
 }
 
+/// Matches a `SyntaxNode` against an `ast` type.
+///
+/// # Example:
+///
+/// ```ignore
+/// match_ast! {
+///     match node {
+///         ast::CallExpr(it) => { ... },
+///         ast::MethodCallExpr(it) => { ... },
+///         ast::MacroCall(it) => { ... },
+///         _ => None,
+///     }
+/// }
+/// ```
 #[macro_export]
 macro_rules! match_ast {
     (match $node:ident {