Fix horizontal trim for block doc comments

compiler/rustc_ast/src/util/comments.rs

@@ -43,15 +43,16 @@ pub fn beautify_doc_string(data: Symbol, kind: CommentKind) -> Symbol {
         if i != 0 || j != lines.len() { Some((i, j)) } else { None }
     }
 
-    fn get_horizontal_trim(lines: &[&str], kind: CommentKind) -> Option<usize> {
+    fn get_horizontal_trim<'a>(lines: &'a [&str], kind: CommentKind) -> Option<String> {
         let mut i = usize::MAX;
         let mut first = true;
 
         // In case we have doc comments like `/**` or `/*!`, we want to remove stars if they are
         // present. However, we first need to strip the empty lines so they don't get in the middle
         // when we try to compute the "horizontal trim".
         let lines = if kind == CommentKind::Block {
-            let mut i = 0;
+            // Whatever happens, we skip the first line.
+            let mut i = if lines[0].trim_start().starts_with('*') { 0 } else { 1 };
             let mut j = lines.len();
 
             while i < j && lines[i].trim().is_empty() {
@@ -84,7 +85,7 @@ pub fn beautify_doc_string(data: Symbol, kind: CommentKind) -> Symbol {
                 return None;
             }
         }
-        Some(i)
+        if lines.is_empty() { None } else { Some(lines[0][..i].into()) }
     }
 
     let data_s = data.as_str();
@@ -102,8 +103,13 @@ pub fn beautify_doc_string(data: Symbol, kind: CommentKind) -> Symbol {
             changes = true;
             // remove a "[ \t]*\*" block from each line, if possible
             for line in lines.iter_mut() {
-                if horizontal + 1 < line.len() {
-                    *line = &line[horizontal + 1..];
+                if let Some(tmp) = line.strip_prefix(&horizontal) {
+                    *line = tmp;
+                    if kind == CommentKind::Block
+                        && (*line == "*" || line.starts_with("* ") || line.starts_with("**"))
+                    {
+                        *line = &line[1..];
+                    }
                 }
             }
         }

compiler/rustc_ast/src/util/comments/tests.rs

@@ -24,7 +24,7 @@ fn test_block_doc_comment_3() {
     create_default_session_globals_then(|| {
         let comment = "\n let a: *i32;\n *a = 5;\n";
         let stripped = beautify_doc_string(Symbol::intern(comment), CommentKind::Block);
-        assert_eq!(stripped.as_str(), " let a: *i32;\n *a = 5;");
+        assert_eq!(stripped.as_str(), "let a: *i32;\n*a = 5;");
     })
 }
 
@@ -41,3 +41,21 @@ fn test_line_doc_comment() {
         assert_eq!(stripped.as_str(), "!test");
     })
 }
+
+#[test]
+fn test_doc_blocks() {
+    create_default_session_globals_then(|| {
+        let stripped =
+            beautify_doc_string(Symbol::intern(" # Returns\n     *\n     "), CommentKind::Block);
+        assert_eq!(stripped.as_str(), " # Returns\n\n");
+
+        let stripped = beautify_doc_string(
+            Symbol::intern("\n     * # Returns\n     *\n     "),
+            CommentKind::Block,
+        );
+        assert_eq!(stripped.as_str(), " # Returns\n\n");
+
+        let stripped = beautify_doc_string(Symbol::intern("\n *     a\n "), CommentKind::Block);
+        assert_eq!(stripped.as_str(), "     a\n");
+    })
+}

src/test/rustdoc-ui/block-doc-comment.rs

@@ -0,0 +1,16 @@
+// check-pass
+// compile-flags:--test
+
+// This test ensures that no code block is detected in the doc comments.
+
+pub mod Wormhole {
+    /** # Returns
+     *
+     */
+    pub fn foofoo() {}
+    /**
+     * # Returns
+     *
+     */
+    pub fn barbar() {}
+}

src/test/rustdoc-ui/block-doc-comment.stdout

@@ -0,0 +1,5 @@
+
+running 0 tests
+
+test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
+

src/test/rustdoc/strip-block-doc-comments-stars.rs

@@ -1,6 +1,6 @@
 #![crate_name = "foo"]
 
-// The goal of this test is to answer that it won't be generated as a list because
+// The goal of this test is to ensure that it won't be generated as a list because
 // block doc comments can have their lines starting with a star.
 
 // @has foo/fn.foo.html