Skip to content

rustdoc: do not include extra stuff in span#157561

Open
notriddle wants to merge 1 commit into
rust-lang:mainfrom
notriddle:do-not-destroy-function-name
Open

rustdoc: do not include extra stuff in span#157561
notriddle wants to merge 1 commit into
rust-lang:mainfrom
notriddle:do-not-destroy-function-name

Conversation

@notriddle
Copy link
Copy Markdown
Contributor

@notriddle notriddle commented Jun 7, 2026

This change prevents our lints from returning a span with stuff in it that isn't actually part of the doc comment. When that happens, it returns None instead.

This change is meant to address rust-lang/rust-clippy#16169, since the bug was reported against the clippy::doc_paragraphs_missing_punctuation lint but is actually a bug in source_span_for_markdown_range_inner.

@rustbot rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Jun 7, 2026
@rustbot
Copy link
Copy Markdown
Collaborator

rustbot commented Jun 7, 2026

r? @lolbinarycat

rustbot has assigned @lolbinarycat.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

  • Owners of files modified in this PR: rustdoc
  • rustdoc expanded to 9 candidates
  • Random selection from GuillaumeGomez, camelid, lolbinarycat

@notriddle
Copy link
Copy Markdown
Contributor Author

notriddle commented Jun 7, 2026

p.s. this change is a lot easier to understand if you use the hide whitespace setting on the diff.

@rust-log-analyzer

This comment has been minimized.

Sign in to view
@notriddle notriddle force-pushed the do-not-destroy-function-name branch from d2784cd to 9af61c5 Compare June 7, 2026 05:52
@rust-log-analyzer

This comment has been minimized.

Sign in to view
@notriddle notriddle force-pushed the do-not-destroy-function-name branch from 9af61c5 to 7db2845 Compare June 7, 2026 07:05
@rust-log-analyzer

This comment has been minimized.

Sign in to view
@notriddle
rustdoc: do not include extra stuff in span
9d216d1 
This change prevents our lints from returning a span with stuff in it
that isn't actually part of the doc comment. When that happens, it
returns `None` instead.
@notriddle notriddle force-pushed the do-not-destroy-function-name branch from 7db2845 to 9d216d1 Compare June 7, 2026 15:26
@rust-log-analyzer
Copy link
Copy Markdown
Collaborator

rust-log-analyzer commented Jun 7, 2026

The job x86_64-gnu-tools failed! Check out the build log: (web) (plain enhanced) (plain)

Click to see the possible cause of the failure (guessed by this bot) 
tests/ui/size_of_in_element_count/functions.rs ... ok
tests/ui/crashes/third-party/conf_allowlisted.rs ... ok

FAILED TEST: tests/ui/doc/unbalanced_ticks.rs
command: CLIPPY_CONF_DIR="tests" RUSTC_ICE="0" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2-tools/x86_64-unknown-linux-gnu/release/clippy-driver" "--error-format=json" "--emit=metadata" "-Aunused" "-Ainternal_features" "-Zui-testing" "-Zdeduplicate-diagnostics=no" "-Dwarnings" "-Ldependency=/checkout/obj/build/x86_64-unknown-linux-gnu/stage2-tools/release/deps" "--sysroot=/checkout/obj/build/x86_64-unknown-linux-gnu/stage2" "--out-dir" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2-tools/ui_test/0/tests/ui/doc" "tests/ui/doc/unbalanced_ticks.rs" "--extern" "futures=/checkout/obj/build/x86_64-unknown-linux-gnu/stage2-tools/x86_64-unknown-linux-gnu/debug/deps/libfutures-fd8ed12b545b74f6.rlib" "--extern" "futures=/checkout/obj/build/x86_64-unknown-linux-gnu/stage2-tools/x86_64-unknown-linux-gnu/debug/deps/libfutures-fd8ed12b545b74f6.rmeta" "--extern" "itertools=/checkout/obj/build/x86_64-unknown-linux-gnu/stage2-tools/x86_64-unknown-linux-gnu/debug/deps/libitertools-9ee748436348a571.rlib" "--extern" "itertools=/checkout/obj/build/x86_64-unknown-linux-gnu/stage2-tools/x86_64-unknown-linux-gnu/debug/deps/libitertools-9ee748436348a571.rmeta" "--extern" "libc=/checkout/obj/build/x86_64-unknown-linux-gnu/stage2-tools/x86_64-unknown-linux-gnu/debug/deps/liblibc-90619423ebd55afe.rlib" "--extern" "libc=/checkout/obj/build/x86_64-unknown-linux-gnu/stage2-tools/x86_64-unknown-linux-gnu/debug/deps/liblibc-90619423ebd55afe.rmeta" "--extern" "parking_lot=/checkout/obj/build/x86_64-unknown-linux-gnu/stage2-tools/x86_64-unknown-linux-gnu/debug/deps/libparking_lot-4abb836a6bc2821a.rlib" "--extern" "parking_lot=/checkout/obj/build/x86_64-unknown-linux-gnu/stage2-tools/x86_64-unknown-linux-gnu/debug/deps/libparking_lot-4abb836a6bc2821a.rmeta" "--extern" "quote=/checkout/obj/build/x86_64-unknown-linux-gnu/stage2-tools/x86_64-unknown-linux-gnu/debug/deps/libquote-4a574c8d844a6f29.rlib" "--extern" "quote=/checkout/obj/build/x86_64-unknown-linux-gnu/stage2-tools/x86_64-unknown-linux-gnu/debug/deps/libquote-4a574c8d844a6f29.rmeta" "--extern" "regex=/checkout/obj/build/x86_64-unknown-linux-gnu/stage2-tools/x86_64-unknown-linux-gnu/debug/deps/libregex-570f05d19c36606e.rlib" "--extern" "regex=/checkout/obj/build/x86_64-unknown-linux-gnu/stage2-tools/x86_64-unknown-linux-gnu/debug/deps/libregex-570f05d19c36606e.rmeta" "--extern" "serde=/checkout/obj/build/x86_64-unknown-linux-gnu/stage2-tools/x86_64-unknown-linux-gnu/debug/deps/libserde-efd3fc3f0a62fb24.rlib" "--extern" "serde=/checkout/obj/build/x86_64-unknown-linux-gnu/stage2-tools/x86_64-unknown-linux-gnu/debug/deps/libserde-efd3fc3f0a62fb24.rmeta" "--extern" "syn=/checkout/obj/build/x86_64-unknown-linux-gnu/stage2-tools/x86_64-unknown-linux-gnu/debug/deps/libsyn-287a95c1501d5684.rlib" "--extern" "syn=/checkout/obj/build/x86_64-unknown-linux-gnu/stage2-tools/x86_64-unknown-linux-gnu/debug/deps/libsyn-287a95c1501d5684.rmeta" "--extern" "tokio=/checkout/obj/build/x86_64-unknown-linux-gnu/stage2-tools/x86_64-unknown-linux-gnu/debug/deps/libtokio-29d18ec391c258da.rlib" "--extern" "tokio=/checkout/obj/build/x86_64-unknown-linux-gnu/stage2-tools/x86_64-unknown-linux-gnu/debug/deps/libtokio-29d18ec391c258da.rmeta" "-L" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2-tools/x86_64-unknown-linux-gnu/debug/deps" "-L" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2-tools/debug/deps" "--edition" "2024"

error: actual output differed from expected
Execute `./x test src/tools/clippy --bless` to update `tests/ui/doc/unbalanced_ticks.stderr` to the actual output
--- tests/ui/doc/unbalanced_ticks.stderr
+++ <stderr output>
---
    |
-LL |   /// This is a doc comment with `unbalanced_tick marks and several words that
-   |  _____^
-LL | |
-LL | | /// should be `encompassed_by` tick marks because they `contain_underscores`.
-LL | | /// Because of the initial `unbalanced_tick` pair, the error message is
-LL | | /// very `confusing_and_misleading`.
-   | |____________________________________^
+LL | /// should be `encompassed_by` tick marks because they `contain_underscores`.
+   |                ^^^^^^^^^^^^^^
    |
-   = help: a backtick may be missing a pair
    = note: `-D clippy::doc-markdown` implied by `-D warnings`
    = help: to override `-D warnings` add `#[allow(clippy::doc_markdown)]`
+help: try
+   |
+LL - /// should be `encompassed_by` tick marks because they `contain_underscores`.
+LL + /// should be ``encompassed_by`` tick marks because they `contain_underscores`.
+   |
 
+error: item in documentation is missing backticks
+  --> tests/ui/doc/unbalanced_ticks.rs:9:57
+   |
+LL | /// should be `encompassed_by` tick marks because they `contain_underscores`.
+   |                                                         ^^^^^^^^^^^^^^^^^^^
+   |
+help: try
+   |
+LL - /// should be `encompassed_by` tick marks because they `contain_underscores`.
+LL + /// should be `encompassed_by` tick marks because they ``contain_underscores``.
+   |
+
+error: item in documentation is missing backticks
+  --> tests/ui/doc/unbalanced_ticks.rs:10:29
+   |
+LL | /// Because of the initial `unbalanced_tick` pair, the error message is
+   |                             ^^^^^^^^^^^^^^^
+   |
+help: try
+   |
+LL - /// Because of the initial `unbalanced_tick` pair, the error message is
+LL + /// Because of the initial ``unbalanced_tick`` pair, the error message is
+   |
+
+error: item in documentation is missing backticks
+  --> tests/ui/doc/unbalanced_ticks.rs:11:11
+   |
+LL | /// very `confusing_and_misleading`.
+   |           ^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+help: try
+   |
+LL - /// very `confusing_and_misleading`.
+LL + /// very ``confusing_and_misleading``.
+   |
+
 error: backticks are unbalanced
   --> tests/ui/doc/unbalanced_ticks.rs:14:5
... 92 lines skipped ...
---
Full unnormalized output:
error: item in documentation is missing backticks
##[error]  --> tests/ui/doc/unbalanced_ticks.rs:9:16
   |
LL | /// should be `encompassed_by` tick marks because they `contain_underscores`.
   |                ^^^^^^^^^^^^^^
   |
   = note: `-D clippy::doc-markdown` implied by `-D warnings`
   = help: to override `-D warnings` add `#[allow(clippy::doc_markdown)]`
help: try
   |
LL - /// should be `encompassed_by` tick marks because they `contain_underscores`.
LL + /// should be ``encompassed_by`` tick marks because they `contain_underscores`.
   |

error: item in documentation is missing backticks
##[error]  --> tests/ui/doc/unbalanced_ticks.rs:9:57
   |
LL | /// should be `encompassed_by` tick marks because they `contain_underscores`.
   |                                                         ^^^^^^^^^^^^^^^^^^^
   |
help: try
   |
LL - /// should be `encompassed_by` tick marks because they `contain_underscores`.
LL + /// should be `encompassed_by` tick marks because they ``contain_underscores``.
   |

error: item in documentation is missing backticks
##[error]  --> tests/ui/doc/unbalanced_ticks.rs:10:29
   |
LL | /// Because of the initial `unbalanced_tick` pair, the error message is
   |                             ^^^^^^^^^^^^^^^
   |
help: try
   |
LL - /// Because of the initial `unbalanced_tick` pair, the error message is
LL + /// Because of the initial ``unbalanced_tick`` pair, the error message is
   |

error: item in documentation is missing backticks
##[error]  --> tests/ui/doc/unbalanced_ticks.rs:11:11
   |
LL | /// very `confusing_and_misleading`.
   |           ^^^^^^^^^^^^^^^^^^^^^^^^
   |
help: try
   |
LL - /// very `confusing_and_misleading`.
LL + /// very ``confusing_and_misleading``.
   |

error: backticks are unbalanced
##[error]  --> tests/ui/doc/unbalanced_ticks.rs:14:5
   |
---

error: backticks are unbalanced
##[error]  --> tests/ui/doc/unbalanced_ticks.rs:20:5
   |
LL | /// Double unbalanced backtick from ``here to here` should lint.
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = help: a backtick may be missing a pair

error: item in documentation is missing backticks
##[error]  --> tests/ui/doc/unbalanced_ticks.rs:34:8
   |
LL | /// ## not_fine
   |        ^^^^^^^^
   |
help: try
   |
LL - /// ## not_fine
LL + /// ## `not_fine`
   |

error: backticks are unbalanced
##[error]  --> tests/ui/doc/unbalanced_ticks.rs:37:5
   |
LL | /// ### `unbalanced
   |     ^^^^^^^^^^^^^^^
   |
   = help: a backtick may be missing a pair

error: backticks are unbalanced
---

error: backticks are unbalanced
##[error]  --> tests/ui/doc/unbalanced_ticks.rs:63:5
   |
LL | /// Escaped \` ` backticks don't count, but unescaped backticks do.
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = help: a backtick may be missing a pair

error: backticks are unbalanced
##[error]  --> tests/ui/doc/unbalanced_ticks.rs:79:9
   |
LL |       /// `Month::from_i64(n: i64)`: | `1`                  | `2`                   | ... | `12`
   |  _________^
LL | |     /// ---------------------------| -------------------- | --------------------- | ... | -----
LL | |     /// ``:                        | Some(Month::January) | Some(Month::February) | ... |
LL | |     /// Some(Month::December)
   | |_____________________________^
   |
   = help: a backtick may be missing a pair

error: aborting due to 14 previous errors
---

error: there were 2 unmatched diagnostics
##[error] --> tests/ui/doc/unbalanced_ticks.rs:9:16
  |
9 | /// should be `encompassed_by` tick marks because they `contain_underscores`.
  |                ^^^^^^^^^^^^^^                           ^^^^^^^^^^^^^^^^^^^ Error[clippy::doc_markdown]: item in documentation is missing backticks
  |                |
  |                Error[clippy::doc_markdown]: item in documentation is missing backticks
  |

error: there was 1 unmatched diagnostic
##[error]  --> tests/ui/doc/unbalanced_ticks.rs:10:29
   |
10 | /// Because of the initial `unbalanced_tick` pair, the error message is
   |                             ^^^^^^^^^^^^^^^ Error[clippy::doc_markdown]: item in documentation is missing backticks
   |

error: there was 1 unmatched diagnostic
##[error]  --> tests/ui/doc/unbalanced_ticks.rs:11:11
   |
11 | /// very `confusing_and_misleading`.
   |           ^^^^^^^^^^^^^^^^^^^^^^^^ Error[clippy::doc_markdown]: item in documentation is missing backticks
   |

full stderr:
error: item in documentation is missing backticks
##[error]  --> tests/ui/doc/unbalanced_ticks.rs:9:16
   |
LL | /// should be `encompassed_by` tick marks because they `contain_underscores`.
   |                ^^^^^^^^^^^^^^
   |
   = note: `-D clippy::doc-markdown` implied by `-D warnings`
   = help: to override `-D warnings` add `#[allow(clippy::doc_markdown)]`
help: try
   |
LL - /// should be `encompassed_by` tick marks because they `contain_underscores`.
LL + /// should be ``encompassed_by`` tick marks because they `contain_underscores`.
   |

error: item in documentation is missing backticks
##[error]  --> tests/ui/doc/unbalanced_ticks.rs:9:57
   |
LL | /// should be `encompassed_by` tick marks because they `contain_underscores`.
   |                                                         ^^^^^^^^^^^^^^^^^^^
   |
help: try
   |
LL - /// should be `encompassed_by` tick marks because they `contain_underscores`.
LL + /// should be `encompassed_by` tick marks because they ``contain_underscores``.
   |

error: item in documentation is missing backticks
##[error]  --> tests/ui/doc/unbalanced_ticks.rs:10:29
   |
LL | /// Because of the initial `unbalanced_tick` pair, the error message is
   |                             ^^^^^^^^^^^^^^^
   |
help: try
   |
LL - /// Because of the initial `unbalanced_tick` pair, the error message is
LL + /// Because of the initial ``unbalanced_tick`` pair, the error message is
   |

error: item in documentation is missing backticks
##[error]  --> tests/ui/doc/unbalanced_ticks.rs:11:11
   |
LL | /// very `confusing_and_misleading`.
   |           ^^^^^^^^^^^^^^^^^^^^^^^^
   |
help: try
   |
LL - /// very `confusing_and_misleading`.
LL + /// very ``confusing_and_misleading``.
   |

error: backticks are unbalanced
##[error]  --> tests/ui/doc/unbalanced_ticks.rs:14:5
   |
---

error: backticks are unbalanced
##[error]  --> tests/ui/doc/unbalanced_ticks.rs:20:5
   |
LL | /// Double unbalanced backtick from ``here to here` should lint.
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = help: a backtick may be missing a pair

error: item in documentation is missing backticks
##[error]  --> tests/ui/doc/unbalanced_ticks.rs:34:8
   |
LL | /// ## not_fine
   |        ^^^^^^^^
   |
help: try
   |
LL - /// ## not_fine
LL + /// ## `not_fine`
   |

error: backticks are unbalanced
##[error]  --> tests/ui/doc/unbalanced_ticks.rs:37:5
   |
LL | /// ### `unbalanced
   |     ^^^^^^^^^^^^^^^
   |
   = help: a backtick may be missing a pair

error: backticks are unbalanced
---

error: backticks are unbalanced
##[error]  --> tests/ui/doc/unbalanced_ticks.rs:63:5
   |
LL | /// Escaped \` ` backticks don't count, but unescaped backticks do.
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = help: a backtick may be missing a pair

error: backticks are unbalanced
##[error]  --> tests/ui/doc/unbalanced_ticks.rs:79:9
   |
LL |       /// `Month::from_i64(n: i64)`: | `1`                  | `2`                   | ... | `12`
   |  _________^
LL | |     /// ---------------------------| -------------------- | --------------------- | ... | -----
LL | |     /// ``:                        | Some(Month::January) | Some(Month::February) | ... |
LL | |     /// Some(Month::December)
   | |_____________________________^
   |
   = help: a backtick may be missing a pair

error: aborting due to 14 previous errors

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@lolbinarycat lolbinarycat

Labels

S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@notriddle @rustbot @rust-log-analyzer @lolbinarycat