Preserve Markdown line breaks in inner and outer block doc comments (#4233)

Author: ayazhafiz

src/formatting/comment.rs

@@ -12,7 +12,7 @@ use crate::formatting::{
     string::{rewrite_string, StringFormat},
     utils::{
         count_newlines, first_line_width, last_line_width, tab_to_spaces,
-        trim_left_preserve_layout, unicode_str_width,
+        trim_end_unless_two_whitespaces, trim_left_preserve_layout, unicode_str_width,
     },
 };
 
@@ -68,9 +68,13 @@ impl<'a> CommentStyle<'a> {
     }
 
     /// Returns `true` if the commenting style is for documentation.
+    /// https://doc.rust-lang.org/reference/comments.html
     pub(crate) fn is_doc_comment(&self) -> bool {
         match *self {
-            CommentStyle::TripleSlash | CommentStyle::Doc => true,
+            CommentStyle::TripleSlash
+            | CommentStyle::Doc
+            | CommentStyle::DoubleBullet
+            | CommentStyle::Exclamation => true,
             _ => false,
         }
     }
@@ -244,6 +248,7 @@ pub(crate) fn combine_strs_with_missing_comments(
 }
 
 pub(crate) fn rewrite_doc_comment(orig: &str, shape: Shape, config: &Config) -> Option<String> {
+    debug!("rewrite_doc_comment: {:?}", orig);
     identify_comment(orig, false, shape, config, true)
 }
 
@@ -253,6 +258,7 @@ pub(crate) fn rewrite_comment(
     shape: Shape,
     config: &Config,
 ) -> Option<String> {
+    debug!("rewrite_comment: {:?}", orig);
     identify_comment(orig, block_style, shape, config, false)
 }
 
@@ -363,7 +369,7 @@ fn identify_comment(
     let (first_group, rest) = orig.split_at(first_group_ending);
     let rewritten_first_group =
         if !config.normalize_comments() && has_bare_lines && style.is_block_comment() {
-            trim_left_preserve_layout(first_group, shape.indent, config)?
+            trim_left_preserve_layout(first_group, shape.indent, config, is_doc_comment)?
         } else if !config.normalize_comments()
             && !config.wrap_comments()
             && !config.format_code_in_doc_comments()
@@ -926,15 +932,6 @@ pub(crate) fn recover_missing_comment_in_span(
     }
 }
 
-/// Trim trailing whitespaces unless they consist of two or more whitespaces.
-fn trim_end_unless_two_whitespaces(s: &str, is_doc_comment: bool) -> &str {
-    if is_doc_comment && s.ends_with("  ") {
-        s
-    } else {
-        s.trim_end()
-    }
-}
-
 /// Trims whitespace and aligns to indent, but otherwise does not change comments.
 fn light_rewrite_comment(
     orig: &str,

src/formatting/macros.rs

@@ -180,7 +180,12 @@ fn return_macro_parse_failure_fallback(
         })
         .unwrap_or(false);
     if is_like_block_indent_style {
-        return trim_left_preserve_layout(context.snippet(span), indent, &context.config);
+        return trim_left_preserve_layout(
+            context.snippet(span),
+            indent,
+            &context.config,
+            /* inside_doc_comment */ false,
+        );
     }
 
     context
@@ -432,7 +437,12 @@ fn rewrite_macro_inner(
             // the `macro_name!` and `{ /* macro_body */ }` but skip modifying
             // anything in between the braces (for now).
             let snippet = context.snippet(mac.span()).trim_start_matches(|c| c != '{');
-            match trim_left_preserve_layout(snippet, shape.indent, &context.config) {
+            match trim_left_preserve_layout(
+                snippet,
+                shape.indent,
+                &context.config,
+                /* inside_doc_comment */ false,
+            ) {
                 Some(macro_body) => Some(format!("{} {}", macro_name, macro_body)),
                 None => Some(format!("{} {}", macro_name, snippet)),
             }

src/formatting/utils.rs

@@ -569,9 +569,12 @@ pub(crate) fn trim_left_preserve_layout(
     orig: &str,
     indent: Indent,
     config: &Config,
+    inside_doc_comment: bool,
 ) -> Option<String> {
     let mut lines = LineClasses::new(orig);
-    let first_line = lines.next().map(|(_, s)| s.trim_end().to_owned())?;
+    let first_line = lines
+        .next()
+        .map(|(_, s)| trim_end_unless_two_whitespaces(&s, inside_doc_comment).to_owned())?;
     let mut trimmed_lines = Vec::with_capacity(16);
 
     let mut veto_trim = false;
@@ -593,7 +596,7 @@ pub(crate) fn trim_left_preserve_layout(
                 trimmed = false;
                 line
             } else {
-                line.trim().to_owned()
+                trim_end_unless_two_whitespaces(line.trim_start(), inside_doc_comment).to_owned()
             };
             trimmed_lines.push((trimmed, line, prefix_space_width));
 
@@ -629,6 +632,16 @@ pub(crate) fn trim_left_preserve_layout(
     )
 }
 
+/// Trim trailing whitespace unless it consists of two or more whitespaces and is in a doc comment.
+/// This is, needed to preserve Markdown's double-space line break syntax.
+pub(crate) fn trim_end_unless_two_whitespaces(s: &str, is_doc_comment: bool) -> &str {
+    if is_doc_comment && s.ends_with("  ") {
+        s
+    } else {
+        s.trim_end()
+    }
+}
+
 /// Based on the given line, determine if the next line can be indented or not.
 /// This allows to preserve the indentation of multi-line literals.
 pub(crate) fn indent_next_line(kind: FullCodeCharKind) -> bool {
@@ -687,8 +700,19 @@ mod test {
         let config = Config::default();
         let indent = Indent::new(4, 0);
         assert_eq!(
-            trim_left_preserve_layout(&s, indent, &config),
+            trim_left_preserve_layout(&s, indent, &config, false),
             Some("aaa\n    bbb\n    ccc".to_string())
         );
     }
+
+    #[test]
+    fn test_trim_left_preserve_layout_no_trim_end_in_doc_comment() {
+        let s = "aaa    \n\tbbb    \n    ccc    ";
+        let config = Config::default();
+        let indent = Indent::new(4, 0);
+        assert_eq!(
+            trim_left_preserve_layout(&s, indent, &config, true),
+            Some("aaa    \n    bbb    \n    ccc    ".to_string())
+        );
+    }
 }

tests/target/issue-3659.rs

@@ -0,0 +1,8 @@
+/*! multiline doc-comment  
+with trailing double space  
+*/
+
+/** multiline doc-comment  
+with trailing double space  
+*/
+fn foo() {}