Add new `invalid_markdown_table` rustdoc lint by GuillaumeGomez · Pull Request #159583 · rust-lang/rust

GuillaumeGomez · 2026-07-19T22:49:30Z

View all comments

Fixes #159186.

r? @Urgau

GuillaumeGomez · 2026-07-21T14:19:25Z

Applied comments.

Urgau

Implementation looks good to me.

View changes since this review

Urgau · 2026-07-21T20:35:29Z

2nd try. Let's do an FCP.

unescaped_pipe_in_table_cell details

`unescaped_pipe_in_table_cell`

This lint is warn-by-default. It detects unescaped pipes (|) in table rows which
lead to some row cells being ignored. For example:

//! | col1 |
//! | ---- |
//! | `code_with(|arg| arg)` |

Which will give:

error: table row has too many columns
  --> $DIR/unescaped_pipe_in_table_cell.rs:5:18
   |
5  | //! | `code_with(|arg| arg)` |
   |                  ^ help: any content after this column divider is discarded
   |
   = help: to escape `|` characters in tables, add a `\` before them like `\|`
note: the lint level is defined here
  --> $DIR/unescaped_pipe_in_table_cell.rs:1:9
   |
1  | #![deny(rustdoc::unescaped_pipe_in_table_cell)]
   |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

@rfcbot merge rustdoc-internals

rust-rfcbot · 2026-07-21T20:35:31Z

@Urgau has proposed to merge this. The next step is review by the rest of the tagged team members:

Concerns:

~~overly specific lint name~~ resolved by Add new invalid_markdown_table rustdoc lint #159583 (comment)

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

camelid · 2026-07-21T20:40:16Z

+```rust
+//! | col1 |
+//! | ---- |
+//! | `code_with(|arg| arg)` |


Wow TIL that this is how GFM works. Very strange design...

View changes since the review

Yeah I was super confused as well.

notriddle · 2026-07-21T22:47:52Z

Minor nits about the implementation, but massive approval for the lint in concept!

camelid · 2026-07-23T20:32:26Z

Definitely in favor of the lint itself, but I wonder if we should have a more generic lint name and then we group together this and any related (current or future) lints about Markdown gotchas? E.g. we have rustdoc::invalid_html_tags that groups together anything related to that, including (soon: #158709) issues when HTML is interleaved with Markdown.

For example, it could be rustdoc::invalid_markdown, or rustdoc::markdown_gotchas, or a Better Name (TM). I could even imagine us renaming rustdoc::invalid_html_tags to something more general like rustdoc::invalid_markdown and including this as part of it.

On a related note, my feeling with #158709 is that additions of new cases to an existing warn-by-default lint do not require FCP since they are not part of stability guarantees, but please let me know if you disagree.

camelid · 2026-07-23T20:33:00Z

@rfcbot reviewed
@rfcbot concern overly specific lint name

GuillaumeGomez · 2026-07-24T14:02:37Z

@camelid: Very fair point. I think having a lint group for all such lints is a good idea. As for the current lint name, I'll rename it as invalid_markdown_table.

rustbot · 2026-07-24T15:59:53Z

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

rust-bors · 2026-08-07T02:04:23Z

This pull request was unapproved.

This PR was contained in a rollup (#160661), which was unapproved.

View changes since this unapproval

… lint

The essential problem is that, with this table: ```text one | ----| a | b | c a | b | a | b a | ``` And this logic: ```rust let too_many_pipes = divider_count > expected_cells + 1; ``` `expected_cells + 1` winds up as 2, so you get this warning: ```text error: unused content after last table cell --> $DIR/invalid_markdown_table.rs:81:14 | LL | //! a | b | c | ^^^^^^ this content is discarded error: unused content after last table cell --> $DIR/invalid_markdown_table.rs:83:14 | LL | //! a | b | | ^^^^ this content is discarded error: unused content after last table cell --> $DIR/invalid_markdown_table.rs:85:14 | LL | //! a | b | ^^ this content is discarded ``` We really want our warning to give the suggest-escaping flow, like this: ```text error: table row has too many columns --> $DIR/invalid_markdown_table.rs:81:13 | LL | //! a | b | c | ^ any content after this column divider is discarded | = help: to escape `|` characters in tables, add a `\` before them like `\|` error: table row has too many columns --> $DIR/invalid_markdown_table.rs:83:13 | LL | //! a | b | | ^ any content after this column divider is discarded | = help: to escape `|` characters in tables, add a `\` before them like `\|` error: unused content after last table cell --> $DIR/invalid_markdown_table.rs:85:14 | LL | //! a | b | ^^ this content is discarded ``` By only scanning the text between the end of the last cell and the row, instead of doing the entire row, we don't have to re-implement as much of pulldown-cmark's logic.

rustbot · 2026-08-24T14:11:56Z

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

GuillaumeGomez · 2026-08-24T15:42:02Z

@bors r=Urgau,notriddle,camelid rollup

rust-bors · 2026-08-24T15:42:05Z

📌 Commit aeb0d4a has been approved by Urgau,notriddle,camelid

It is now in the queue for this repository.

@Urgau