From e3942874a06677f17be284f27b5494531cc7224a Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Sat, 5 Feb 2022 14:45:29 +0100 Subject: [PATCH 1/3] Fix horizontal trim for block doc comments --- compiler/rustc_ast/src/util/comments.rs | 16 +++++++---- compiler/rustc_ast/src/util/comments/tests.rs | 28 ++++++++++++++++++- 2 files changed, 38 insertions(+), 6 deletions(-) diff --git a/compiler/rustc_ast/src/util/comments.rs b/compiler/rustc_ast/src/util/comments.rs index 612ee71f350f1..f51b0086dc8b6 100644 --- a/compiler/rustc_ast/src/util/comments.rs +++ b/compiler/rustc_ast/src/util/comments.rs @@ -43,7 +43,7 @@ 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 { + fn get_horizontal_trim<'a>(lines: &'a [&str], kind: CommentKind) -> Option { let mut i = usize::MAX; let mut first = true; @@ -51,7 +51,8 @@ pub fn beautify_doc_string(data: Symbol, kind: CommentKind) -> Symbol { // 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..]; + } } } } diff --git a/compiler/rustc_ast/src/util/comments/tests.rs b/compiler/rustc_ast/src/util/comments/tests.rs index 98f692a7724e2..0b8772947e6e9 100644 --- a/compiler/rustc_ast/src/util/comments/tests.rs +++ b/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,29 @@ 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 + * + ", + ), + CommentKind::Block, + ); + assert_eq!(stripped.as_str(), " # Returns\n\n"); + + let stripped = beautify_doc_string( + Symbol::intern( + " + * # Returns + * + ", + ), + CommentKind::Block, + ); + assert_eq!(stripped.as_str(), " # Returns\n\n"); + }) +} From 33cbf8908d4cf1c971128ee35e7bd2ea50225b63 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Sun, 6 Feb 2022 22:21:09 +0100 Subject: [PATCH 2/3] Add test for block doc comments horizontal trim --- compiler/rustc_ast/src/util/comments/tests.rs | 20 ++++++------------- src/test/rustdoc-ui/block-doc-comment.rs | 16 +++++++++++++++ src/test/rustdoc-ui/block-doc-comment.stdout | 5 +++++ 3 files changed, 27 insertions(+), 14 deletions(-) create mode 100644 src/test/rustdoc-ui/block-doc-comment.rs create mode 100644 src/test/rustdoc-ui/block-doc-comment.stdout diff --git a/compiler/rustc_ast/src/util/comments/tests.rs b/compiler/rustc_ast/src/util/comments/tests.rs index 0b8772947e6e9..11d50603a1011 100644 --- a/compiler/rustc_ast/src/util/comments/tests.rs +++ b/compiler/rustc_ast/src/util/comments/tests.rs @@ -45,25 +45,17 @@ fn test_line_doc_comment() { #[test] fn test_doc_blocks() { create_default_session_globals_then(|| { - let stripped = beautify_doc_string( - Symbol::intern( - " # Returns - * - ", - ), - CommentKind::Block, - ); + 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( - " - * # Returns - * - ", - ), + 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"); }) } diff --git a/src/test/rustdoc-ui/block-doc-comment.rs b/src/test/rustdoc-ui/block-doc-comment.rs new file mode 100644 index 0000000000000..c60dfa3f9518e --- /dev/null +++ b/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() {} +} diff --git a/src/test/rustdoc-ui/block-doc-comment.stdout b/src/test/rustdoc-ui/block-doc-comment.stdout new file mode 100644 index 0000000000000..e5c27bebbdb23 --- /dev/null +++ b/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 + From a476ec8bd0b1925d349383110b75ff51567d7534 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Sun, 6 Feb 2022 22:51:47 +0100 Subject: [PATCH 3/3] Update rustdoc test --- src/test/rustdoc/strip-block-doc-comments-stars.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/test/rustdoc/strip-block-doc-comments-stars.rs b/src/test/rustdoc/strip-block-doc-comments-stars.rs index ed2297b4fac5d..ea28d84f1ffdf 100644 --- a/src/test/rustdoc/strip-block-doc-comments-stars.rs +++ b/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