improve doc attr span tracking for proc-macro

book/src/lint_configuration.md

@@ -640,7 +640,7 @@ default configuration of Clippy. By default, any configuration will replace the
 * `doc-valid-idents = ["ClipPy"]` would replace the default list with `["ClipPy"]`.
 * `doc-valid-idents = ["ClipPy", ".."]` would append `ClipPy` to the default list.
 
-**Default Value:** `["KiB", "MiB", "GiB", "TiB", "PiB", "EiB", "MHz", "GHz", "THz", "AccessKit", "CoAP", "CoreFoundation", "CoreGraphics", "CoreText", "DevOps", "Direct2D", "Direct3D", "DirectWrite", "DirectX", "ECMAScript", "GPLv2", "GPLv3", "GitHub", "GitLab", "IPv4", "IPv6", "InfiniBand", "RoCE", "ClojureScript", "CoffeeScript", "JavaScript", "PostScript", "PureScript", "TypeScript", "PowerPC", "PowerShell", "WebAssembly", "NaN", "NaNs", "OAuth", "GraphQL", "SQLite", "MySQL", "PostgreSQL", "MariaDB", "MongoDB", "OCaml", "OpenAL", "OpenDNS", "OpenGL", "OpenMP", "OpenSSH", "OpenSSL", "OpenStreetMap", "OpenTelemetry", "OpenType", "WebAuthn", "WebGL", "WebGL2", "WebGPU", "WebRTC", "WebSocket", "WebTransport", "WebP", "OpenExr", "YCbCr", "sRGB", "TensorFlow", "TrueType", "iOS", "macOS", "FreeBSD", "NetBSD", "OpenBSD", "NixOS", "TeX", "LaTeX", "BibTeX", "BibLaTeX", "MinGW", "CamelCase"]`
+**Default Value:** `["KiB", "MiB", "GiB", "TiB", "PiB", "EiB", "MHz", "GHz", "THz", "AccessKit", "CoAP", "CoreFoundation", "CoreGraphics", "CoreText", "DevOps", "Direct2D", "Direct3D", "DirectWrite", "DirectX", "ECMAScript", "GPLv2", "GPLv3", "GitHub", "GitLab", "IPv4", "IPv6", "InfiniBand", "RoCE", "ClojureScript", "CoffeeScript", "JavaScript", "PostScript", "PureScript", "TypeScript", "PowerPC", "PowerShell", "WebAssembly", "NaN", "NaNs", "OAuth", "GraphQL", "SQLite", "MySQL", "PostgreSQL", "MariaDB", "MongoDB", "OCaml", "OpenAL", "OpenDNS", "OpenGL", "OpenMP", "OpenSSH", "OpenSSL", "OpenStreetMap", "OpenTelemetry", "OpenType", "WebAuthn", "WebGL", "WebGL2", "WebGPU", "WebRTC", "WebSocket", "WebTransport", "WebP", "OpenExr", "YCbCr", "sRGB", "TensorFlow", "TrueType", "iOS", "macOS", "FreeBSD", "NetBSD", "OpenBSD", "NixOS", "TeX", "LaTeX", "BibTeX", "BibLaTeX", "MinGW", "CamelCase", "x86_64", "CommonMark", "IntelliJ"]`
 
 ---
 **Affected lints:**

clippy_config/src/conf.rs

@@ -45,6 +45,8 @@ static DEFAULT_DOC_VALID_IDENTS: &[&str] = &[
     "TeX", "LaTeX", "BibTeX", "BibLaTeX",
     "MinGW",
     "CamelCase",
+    "x86_64",
+    "CommonMark", "IntelliJ",
 ];
 static DEFAULT_DISALLOWED_NAMES: &[&str] = &["foo", "baz", "quux"];
 static DEFAULT_ALLOWED_IDENTS_BELOW_MIN_CHARS: &[&str] = &["i", "j", "x", "y", "z", "w", "n"];

clippy_lints/src/arbitrary_source_item_ordering.rs

@@ -58,13 +58,13 @@ declare_clippy_lint! {
     ///
     /// | Group              | Item Kinds           |
     /// |--------------------|----------------------|
-    /// | `modules`          | "mod", "foreign_mod" |
-    /// | `use`              | "use"                |
-    /// | `macros`           | "macro"              |
-    /// | `global_asm`       | "global_asm"         |
-    /// | `UPPER_SNAKE_CASE` | "static", "const"    |
-    /// | `PascalCase`       | "ty_alias", "opaque_ty", "enum", "struct", "union", "trait", "trait_alias", "impl" |
-    /// | `lower_snake_case` | "fn"                 |
+    /// | `modules`          | `mod`, `foreign_mod` |
+    /// | `use`              | `use`                |
+    /// | `macros`           | `macro`              |
+    /// | `global_asm`       | `global_asm`         |
+    /// | `UPPER_SNAKE_CASE` | `static`, `const`    |
+    /// | `PascalCase`       | `ty_alias`, `opaque_ty`, `enum`, `struct`, `union`, `trait`, `trait_alias`, `impl` |
+    /// | `lower_snake_case` | `fn`                 |
     ///
     /// The groups' names are arbitrary and can be changed to suit the
     /// conventions that should be enforced for a specific project.

clippy_lints/src/attrs/mod.rs

@@ -83,7 +83,7 @@ declare_clippy_lint! {
 
 declare_clippy_lint! {
     /// ### What it does
-    /// Checks for `warn`/`deny`/`forbid` attributes targeting the whole clippy::restriction category.
+    /// Checks for `warn`/`deny`/`forbid` attributes targeting the whole `clippy::restriction` category.
     ///
     /// ### Why is this bad?
     /// Restriction lints sometimes are in contrast with other lints or even go against idiomatic rust.
@@ -110,12 +110,12 @@ declare_clippy_lint! {
     /// with `#[rustfmt::skip]`.
     ///
     /// ### Why is this bad?
-    /// Since tool_attributes ([rust-lang/rust#44690](https://github.com/rust-lang/rust/issues/44690))
+    /// Since `tool_attributes` ([rust-lang/rust#44690](https://github.com/rust-lang/rust/issues/44690))
     /// are stable now, they should be used instead of the old `cfg_attr(rustfmt)` attributes.
     ///
     /// ### Known problems
     /// This lint doesn't detect crate level inner attributes, because they get
-    /// processed before the PreExpansionPass lints get executed. See
+    /// processed before the pre-expansion pass lints get executed. See
     /// [#3123](https://github.com/rust-lang/rust-clippy/pull/3123#issuecomment-422321765)
     ///
     /// ### Example
@@ -432,22 +432,22 @@ declare_clippy_lint! {
     ///
     /// This lint permits lint attributes for lints emitted on the items themself.
     /// For `use` items these lints are:
-    /// * ambiguous_glob_reexports
-    /// * dead_code
-    /// * deprecated
-    /// * hidden_glob_reexports
-    /// * unreachable_pub
-    /// * unused
-    /// * unused_braces
-    /// * unused_import_braces
-    /// * clippy::disallowed_types
-    /// * clippy::enum_glob_use
-    /// * clippy::macro_use_imports
-    /// * clippy::module_name_repetitions
-    /// * clippy::redundant_pub_crate
-    /// * clippy::single_component_path_imports
-    /// * clippy::unsafe_removed_from_name
-    /// * clippy::wildcard_imports
+    /// * `ambiguous_glob_reexports`
+    /// * `dead_code`
+    /// * `deprecated`
+    /// * `hidden_glob_reexports`
+    /// * `unreachable_pub`
+    /// * `unused`
+    /// * `unused_braces`
+    /// * `unused_import_braces`
+    /// * `clippy::disallowed_types`
+    /// * `clippy::enum_glob_use`
+    /// * `clippy::macro_use_imports`
+    /// * `clippy::module_name_repetitions`
+    /// * `clippy::redundant_pub_crate`
+    /// * `clippy::single_component_path_imports`
+    /// * `clippy::unsafe_removed_from_name`
+    /// * `clippy::wildcard_imports`
     ///
     /// For `extern crate` items these lints are:
     /// * `unused_imports` on items with `#[macro_use]`

clippy_lints/src/bool_to_int_with_if.rs

@@ -15,7 +15,7 @@ declare_clippy_lint! {
     /// Coercion or `from()` is another way to convert bool to a number.
     /// Both methods are guaranteed to return 1 for true, and 0 for false.
     ///
-    /// See https://doc.rust-lang.org/std/primitive.bool.html#impl-From%3Cbool%3E
+    /// See <https://doc.rust-lang.org/std/primitive.bool.html#impl-From%3Cbool%3E-for-u8>
     ///
     /// ### Example
     /// ```no_run

clippy_lints/src/crate_in_macro_def.rs

@@ -14,7 +14,7 @@ declare_clippy_lint! {
     /// ### Why is this bad?
     /// `crate` refers to the macro call's crate, whereas `$crate` refers to the macro definition's
     /// crate. Rarely is the former intended. See:
-    /// https://doc.rust-lang.org/reference/macros-by-example.html#hygiene
+    /// <https://doc.rust-lang.org/reference/macros-by-example.html#hygiene>
     ///
     /// ### Example
     /// ```no_run

clippy_lints/src/default.rs

@@ -37,7 +37,7 @@ declare_clippy_lint! {
 declare_clippy_lint! {
     /// ### What it does
     /// Checks for immediate reassignment of fields initialized
-    /// with Default::default().
+    /// with `Default::default()`.
     ///
     /// ### Why is this bad?
     ///It's more idiomatic to use the [functional update syntax](https://doc.rust-lang.org/reference/expressions/struct-expr.html#functional-update-syntax).

clippy_lints/src/doc/mod.rs

@@ -1,7 +1,9 @@
 use clippy_config::Conf;
 use clippy_utils::attrs::is_doc_hidden;
 use clippy_utils::diagnostics::{span_lint, span_lint_and_help, span_lint_and_then};
-use clippy_utils::{is_entrypoint_fn, is_trait_impl_item};
+use clippy_utils::macros::root_macro_call;
+use clippy_utils::{is_entrypoint_fn, is_trait_impl_item, sym};
+use rustc_ast::token::DocFragmentKind;
 use rustc_attr_ir::Attribute;
 use rustc_data_structures::fx::FxHashSet;
 use rustc_errors::Applicability;
@@ -263,7 +265,7 @@ declare_clippy_lint! {
     /// /// Consume the array and return the inner
     /// /// [`SmallVec<[T; INLINE_CAPACITY]>`][SmallVec].
     /// /// [SmallVec]: SmallVec
-    /// fn main() {}
+    /// fn foo() {}
     /// ```
     #[clippy::version = "pre 1.29.0"]
     pub DOC_MARKDOWN,
@@ -878,11 +880,15 @@ fn check_attrs(cx: &LateContext<'_>, valid_idents: &FxHashSet<String>, attrs: &[
 
     let (fragments, _) = attrs_to_doc_fragments(
         attrs.iter().filter_map(|attr| {
-            if attr.doc_str_and_fragment_kind().is_none() || attr.span().in_external_macro(cx.sess().source_map()) {
-                None
-            } else {
-                Some((attr, None))
-            }
+            let (_, kind) = attr.doc_str_and_fragment_kind()?;
+            let (is_raw, doc_str_span) = match kind {
+                DocFragmentKind::Sugared(_) => (false, attr.span()),
+                DocFragmentKind::Raw(span) => (true, span),
+            };
+            let from_include_str_macro = is_raw
+                && !attr.span().in_external_macro(cx.sess().source_map())
+                && originated_from_include_str_macro(cx, doc_str_span);
+            (from_include_str_macro || !doc_str_span.in_external_macro(cx.sess().source_map())).then_some((attr, None))
         }),
         true,
     );
@@ -963,6 +969,10 @@ fn check_attrs(cx: &LateContext<'_>, valid_idents: &FxHashSet<String>, attrs: &[
     ))
 }
 
+fn originated_from_include_str_macro(cx: &LateContext<'_>, span: Span) -> bool {
+    root_macro_call(span).is_some_and(|macro_call| cx.tcx.is_diagnostic_item(sym::include_str_macro, macro_call.def_id))
+}
+
 enum Container {
     Blockquote,
     List(usize),

clippy_lints/src/loops/mod.rs

@@ -333,7 +333,7 @@ declare_clippy_lint! {
 
 declare_clippy_lint! {
     /// ### What it does
-    /// Checks for manual implementations of Iterator::find
+    /// Checks for manual implementations of `Iterator::find`
     ///
     /// ### Why is this bad?
     /// It doesn't affect performance, but using `find` is shorter and easier to read.

clippy_lints/src/main_recursion.rs

@@ -1,3 +1,5 @@
+#![expect(clippy::needless_doctest_main)]
+
 use clippy_utils::diagnostics::span_lint_and_help;
 use clippy_utils::source::snippet;
 use clippy_utils::{is_entrypoint_fn, is_no_std_crate};
@@ -9,8 +11,8 @@ declare_clippy_lint! {
     /// Checks for recursion using the entrypoint.
     ///
     /// ### Why is this bad?
-    /// Apart from special setups (which we could detect following attributes like #![no_std]),
-    /// recursing into main() seems like an unintuitive anti-pattern we should be able to detect.
+    /// Apart from special setups (which we could detect following attributes like `#![no_std]`),
+    /// recursing into `main()` seems like an unintuitive anti-pattern we should be able to detect.
     ///
     /// ### Example
     /// ```no_run

clippy_lints/src/methods/mod.rs

@@ -997,7 +997,7 @@ declare_clippy_lint! {
     /// `x.last()`.  Indexing into the array will panic on out-of-bounds
     /// accesses, while `x.get()` and `x.last()` will return `None`.
     ///
-    /// There is another lint (get_unwrap) that covers the case of using
+    /// There is another lint (`get_unwrap`) that covers the case of using
     /// `x.get(index).unwrap()` instead of `x[index]`.
     ///
     /// ### Example
@@ -2907,7 +2907,7 @@ declare_clippy_lint! {
 
 declare_clippy_lint! {
     /// ### What it does
-    /// Checks for usage of `_.as_ref().map(Deref::deref)` or its aliases (such as String::as_str).
+    /// Checks for usage of `_.as_ref().map(Deref::deref)` or its aliases (such as `String::as_str`).
     ///
     /// ### Why is this bad?
     /// Readability, this can be written more concisely as
@@ -3923,9 +3923,8 @@ declare_clippy_lint! {
 
 declare_clippy_lint! {
     /// ### What it does
-    /// Checks for calls to [`splitn`]
-    /// (https://doc.rust-lang.org/std/primitive.str.html#method.splitn) and
-    /// related functions with either zero or one splits.
+    /// Checks for calls to [`splitn`](https://doc.rust-lang.org/std/primitive.str.html#method.splitn)
+    /// and related functions with either zero or one splits.
     ///
     /// ### Why is this bad?
     /// These calls don't actually split the value and are
@@ -4501,7 +4500,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for unnecessary calls to `min()` or `max()` in the following cases
     /// - Either both side is constant
-    /// - One side is clearly larger than the other, like i32::MIN and an i32 variable
+    /// - One side is clearly larger than the other, like `i32::MIN` and an `i32` variable
     ///
     /// ### Why is this bad?
     ///
@@ -4830,7 +4829,7 @@ declare_clippy_lint! {
 
 declare_clippy_lint! {
     /// ### What it does
-    /// Checks for usage of File::read_to_end and File::read_to_string.
+    /// Checks for usage of ``File::read_to_end`` and `File::read_to_string`.
     ///
     /// ### Why restrict this?
     /// `fs::{read, read_to_string}` provide the same functionality when `buf` is empty with fewer imports and no intermediate values.
@@ -4903,7 +4902,7 @@ declare_clippy_lint! {
     /// Clippy allows `Pin<&Self>` and `Pin<&mut Self>` if `&self` and `&mut self` is required.
     ///
     /// Please find more info here:
-    /// https://rust-lang.github.io/api-guidelines/naming.html#ad-hoc-conversions-follow-as_-to_-into_-conventions-c-conv
+    /// <https://rust-lang.github.io/api-guidelines/naming.html#ad-hoc-conversions-follow-as_-to_-into_-conventions-c-conv>
     ///
     /// ### Why is this bad?
     /// Consistency breeds readability. If you follow the

clippy_lints/src/misc_early/mod.rs

@@ -277,21 +277,15 @@ declare_clippy_lint! {
     ///
     /// In Rust:
     /// ```no_run
-    /// fn main() {
-    ///     let a = 0123;
-    ///     println!("{}", a);
-    /// }
+    /// let a = 0123;
+    /// println!("{}", a);
     /// ```
     ///
     /// prints `123`, while in C:
     ///
     /// ```c
-    /// #include <stdio.h>
-    ///
-    /// int main() {
-    ///     int a = 0123;
-    ///     printf("%d\n", a);
-    /// }
+    /// int a = 0123;
+    /// printf("%d\n", a);
     /// ```
     ///
     /// prints `83` (as `83 == 0o123` while `123 == 0o173`).

clippy_lints/src/missing_const_for_thread_local.rs

@@ -21,7 +21,7 @@ declare_clippy_lint! {
     /// need to be dropped, this can enable an even more efficient implementation that
     /// does not need to track any additional state.
     ///
-    /// https://doc.rust-lang.org/std/macro.thread_local.html
+    /// <https://doc.rust-lang.org/std/macro.thread_local.html>
     ///
     /// ### Example
     /// ```no_run

clippy_lints/src/strlen_on_c_strings.rs

@@ -16,7 +16,7 @@ declare_clippy_lint! {
     /// and suggest calling `count_bytes()` instead.
     ///
     /// ### Why is this bad?
-    /// libc::strlen is an unsafe function, which we don't need to call
+    /// `libc::strlen` is an unsafe function, which we don't need to call
     /// if all we want to know is the length of the c-string.
     ///
     /// ### Example

clippy_lints/src/suspicious_trait_impl.rs

@@ -32,8 +32,8 @@ declare_clippy_lint! {
 
 declare_clippy_lint! {
     /// ### What it does
-    /// Lints for suspicious operations in impls of OpAssign, e.g.
-    /// subtracting elements in an AddAssign impl.
+    /// Lints for suspicious operations in impls of `OpAssign`, e.g.
+    /// subtracting elements in an `AddAssign` impl.
     ///
     /// ### Why is this bad?
     /// This is probably a typo or copy-and-paste error and not intended.

clippy_lints/src/swap.rs

@@ -63,7 +63,7 @@ declare_clippy_lint! {
     /// b = a;
     /// a = t;
     /// ```
-    /// Use std::mem::swap():
+    /// Use `std::mem::swap()`:
     /// ```no_run
     /// let mut a = 1;
     /// let mut b = 2;

clippy_lints/src/transmute/mod.rs

@@ -241,7 +241,7 @@ declare_clippy_lint! {
     /// ### Why is this bad?
     /// Creating a null function pointer is undefined behavior.
     ///
-    /// More info: https://doc.rust-lang.org/nomicon/ffi.html#the-nullable-pointer-optimization
+    /// More info: <https://doc.rust-lang.org/nomicon/ffi.html#the-nullable-pointer-optimization>
     ///
     /// ### Known problems
     /// Not all cases can be detected at the moment of this writing.

clippy_lints/src/unit_return_expecting_ord.rs

@@ -9,18 +9,18 @@ use rustc_span::{BytePos, Span, Symbol, sym};
 declare_clippy_lint! {
     /// ### What it does
     /// Checks for functions that expect closures of type
-    /// Fn(...) -> Ord where the implemented closure returns the unit type.
+    /// `Fn(...) -> Ord` where the implemented closure returns the unit type.
     /// The lint also suggests to remove the semi-colon at the end of the statement if present.
     ///
     /// ### Why is this bad?
     /// Likely, returning the unit type is unintentional, and
-    /// could simply be caused by an extra semi-colon. Since () implements Ord
+    /// could simply be caused by an extra semi-colon. Since `()` implements `Ord`
     /// it doesn't cause a compilation error.
-    /// This is the same reasoning behind the unit_cmp lint.
+    /// This is the same reasoning behind the `unit_cmp` lint.
     ///
     /// ### Known problems
     /// If returning unit is intentional, then there is no
-    /// way of specifying this without triggering needless_return lint
+    /// way of specifying this without triggering `needless_return` lint
     ///
     /// ### Example
     /// ```no_run

clippy_lints/src/unnecessary_self_imports.rs

@@ -13,7 +13,7 @@ declare_clippy_lint! {
     ///
     /// ### Known problems
     /// Removing `::{self}` will cause any non-module items at the same path to also be imported.
-    /// This might cause a naming conflict (https://github.com/rust-lang/rustfmt/issues/3568). This lint makes no attempt
+    /// This might cause a [naming conflict](https://github.com/rust-lang/rustfmt/issues/3568). This lint makes no attempt
     /// to detect this scenario and that is why it is a restriction lint.
     ///
     /// ### Example