Improve doc comment unicode guidance

compiler/rustc_parse/src/errors.rs

@@ -4344,7 +4344,7 @@ fn add_to_diag<G: EmissionGuarantee>(self, diag: &mut Diag<'_, G>) {
 
 pub(crate) enum HiddenUnicodeCodepointsDiagSub {
     Escape { spans: Vec<(char, Span)> },
-    NoEscape { spans: Vec<(char, Span)> },
+    NoEscape { spans: Vec<(char, Span)>, is_doc_comment: bool },
 }
 
 // Used because of multiple multipart_suggestion and note
@@ -4370,7 +4370,7 @@ fn add_to_diag<G: EmissionGuarantee>(self, diag: &mut Diag<'_, G>) {
                     Applicability::MachineApplicable,
                 );
             }
-            HiddenUnicodeCodepointsDiagSub::NoEscape { spans } => {
+            HiddenUnicodeCodepointsDiagSub::NoEscape { spans, is_doc_comment } => {
                 // FIXME: in other suggestions we've reversed the inner spans of doc comments. We
                 // should do the same here to provide the same good suggestions as we do for
                 // literals above.
@@ -4383,7 +4383,11 @@ fn add_to_diag<G: EmissionGuarantee>(self, diag: &mut Diag<'_, G>) {
                         .join(", "),
                 );
                 diag.note(msg!("if their presence wasn't intentional, you can remove them"));
-                diag.note(msg!("if you want to keep them but make them visible in your source code, you can escape them: {$escaped}"));
+                if is_doc_comment {
+                    diag.note(msg!(r#"if you need to keep them and make them explicit in source, rewrite this doc comment as a `#[doc = "..."]` attribute and use Unicode escapes such as {$escaped}"#));
+                } else {
+                    diag.note(msg!("if you want to keep them but make them visible in your source code, you can escape them: {$escaped}"));
+                }
             }
         }
     }

compiler/rustc_parse/src/lexer/mod.rs

@@ -546,6 +546,7 @@ fn lint_doc_comment_unicode_text_flow(&mut self, start: BytePos, content: &str)
                 self.mk_sp(start, self.pos),
                 0,
                 false,
+                true,
                 "doc comment",
             );
         }
@@ -580,6 +581,7 @@ fn lint_literal_unicode_text_flow(
             span,
             padding,
             point_at_inner_spans,
+            false,
             label,
         );
     }
@@ -590,6 +592,7 @@ fn report_text_direction_codepoint(
         span: Span,
         padding: u32,
         point_at_inner_spans: bool,
+        is_doc_comment: bool,
         label: &str,
     ) {
         // Obtain the `Span`s for each of the forbidden chars.
@@ -610,7 +613,7 @@ fn report_text_direction_codepoint(
         let sub = if point_at_inner_spans && !spans.is_empty() {
             errors::HiddenUnicodeCodepointsDiagSub::Escape { spans }
         } else {
-            errors::HiddenUnicodeCodepointsDiagSub::NoEscape { spans }
+            errors::HiddenUnicodeCodepointsDiagSub::NoEscape { spans, is_doc_comment }
         };
 
         self.psess.buffer_lint(

tests/ui/parser/macro/unicode-control-codepoints-macros.stderr

@@ -6,7 +6,7 @@ LL |         /// �test� RTL in doc in vec
    |
    = note: these kind of unicode codepoints change the way text flows on applications that support them, but can cause confusion because they change the order of characters on the screen
    = note: if their presence wasn't intentional, you can remove them
-   = note: if you want to keep them but make them visible in your source code, you can escape them: '\u{202e}', '\u{2066}'
+   = note: if you need to keep them and make them explicit in source, rewrite this doc comment as a `#[doc = "..."]` attribute and use Unicode escapes such as '\u{202e}', '\u{2066}'
    = note: `#[deny(text_direction_codepoint_in_literal)]` on by default
 
 error: unicode codepoint changing visible direction of text present in doc comment
@@ -19,7 +19,7 @@ LL | |          */
    |
    = note: these kind of unicode codepoints change the way text flows on applications that support them, but can cause confusion because they change the order of characters on the screen
    = note: if their presence wasn't intentional, you can remove them
-   = note: if you want to keep them but make them visible in your source code, you can escape them: '\u{202e}', '\u{2066}'
+   = note: if you need to keep them and make them explicit in source, rewrite this doc comment as a `#[doc = "..."]` attribute and use Unicode escapes such as '\u{202e}', '\u{2066}'
 
 error: unicode codepoint changing visible direction of text present in doc comment
   --> $DIR/unicode-control-codepoints-macros.rs:33:9
@@ -31,7 +31,7 @@ LL | |          */
    |
    = note: these kind of unicode codepoints change the way text flows on applications that support them, but can cause confusion because they change the order of characters on the screen
    = note: if their presence wasn't intentional, you can remove them
-   = note: if you want to keep them but make them visible in your source code, you can escape them: '\u{202e}', '\u{2066}'
+   = note: if you need to keep them and make them explicit in source, rewrite this doc comment as a `#[doc = "..."]` attribute and use Unicode escapes such as '\u{202e}', '\u{2066}'
 
 error: unicode codepoint changing visible direction of text present in doc comment
   --> $DIR/unicode-control-codepoints-macros.rs:41:9
@@ -41,7 +41,7 @@ LL |         /// �test� RTL in doc in proc macro
    |
    = note: these kind of unicode codepoints change the way text flows on applications that support them, but can cause confusion because they change the order of characters on the screen
    = note: if their presence wasn't intentional, you can remove them
-   = note: if you want to keep them but make them visible in your source code, you can escape them: '\u{202e}', '\u{2066}'
+   = note: if you need to keep them and make them explicit in source, rewrite this doc comment as a `#[doc = "..."]` attribute and use Unicode escapes such as '\u{202e}', '\u{2066}'
 
 error: unicode codepoint changing visible direction of text present in doc comment
   --> $DIR/unicode-control-codepoints-macros.rs:46:9
@@ -51,7 +51,7 @@ LL |         /// �test� RTL in doc in proc macro
    |
    = note: these kind of unicode codepoints change the way text flows on applications that support them, but can cause confusion because they change the order of characters on the screen
    = note: if their presence wasn't intentional, you can remove them
-   = note: if you want to keep them but make them visible in your source code, you can escape them: '\u{202e}', '\u{2066}'
+   = note: if you need to keep them and make them explicit in source, rewrite this doc comment as a `#[doc = "..."]` attribute and use Unicode escapes such as '\u{202e}', '\u{2066}'
 
 error: aborting due to 5 previous errors
 

tests/ui/parser/unicode-control-codepoints.stderr

@@ -232,7 +232,7 @@ LL | /**  '�'); */fn foo() {}
    |
    = note: these kind of unicode codepoints change the way text flows on applications that support them, but can cause confusion because they change the order of characters on the screen
    = note: if their presence wasn't intentional, you can remove them
-   = note: if you want to keep them but make them visible in your source code, you can escape them: '\u{202e}'
+   = note: if you need to keep them and make them explicit in source, rewrite this doc comment as a `#[doc = "..."]` attribute and use Unicode escapes such as '\u{202e}'
 
 error: unicode codepoint changing visible direction of text present in doc comment
   --> $DIR/unicode-control-codepoints.rs:46:1
@@ -244,7 +244,7 @@ LL | |  *  '�'); */fn bar() {}
    |
    = note: these kind of unicode codepoints change the way text flows on applications that support them, but can cause confusion because they change the order of characters on the screen
    = note: if their presence wasn't intentional, you can remove them
-   = note: if you want to keep them but make them visible in your source code, you can escape them: '\u{202e}'
+   = note: if you need to keep them and make them explicit in source, rewrite this doc comment as a `#[doc = "..."]` attribute and use Unicode escapes such as '\u{202e}'
 
 error: aborting due to 20 previous errors
 

tests/ui/parser/unicode-control-doc-comment-issue-153096.rs

@@ -0,0 +1,8 @@
+//@ edition: 2024
+
+#[allow(unused)]
+/// ⁨א⁩, ⁨ב⁩, ⁨ג⁩, ⁨ד⁩, ⁨ה⁩
+//~^ ERROR unicode codepoint changing visible direction of text present in doc comment
+fn foo() {}
+
+fn main() {}

tests/ui/parser/unicode-control-doc-comment-issue-153096.stderr

@@ -0,0 +1,13 @@
+error: unicode codepoint changing visible direction of text present in doc comment
+  --> $DIR/unicode-control-doc-comment-issue-153096.rs:4:1
+   |
+LL | /// �א�, �ב�, �ג�, �ד�, �ה�
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ this doc comment contains invisible unicode text flow control codepoints
+   |
+   = note: these kind of unicode codepoints change the way text flows on applications that support them, but can cause confusion because they change the order of characters on the screen
+   = note: if their presence wasn't intentional, you can remove them
+   = note: if you need to keep them and make them explicit in source, rewrite this doc comment as a `#[doc = "..."]` attribute and use Unicode escapes such as '\u{2068}', '\u{2069}', '\u{2068}', '\u{2069}', '\u{2068}', '\u{2069}', '\u{2068}', '\u{2069}', '\u{2068}', '\u{2069}'
+   = note: `#[deny(text_direction_codepoint_in_literal)]` on by default
+
+error: aborting due to 1 previous error
+