Rustdoc does not display a table in some cases involving whitespaces

[dutchmartin]

When placing a space between the line comment start //! and the start of the table |, the table does not render properly:

//! # Lorem ispum cratus test amet
//!
//!This table has no space between the `//!` and the table start character `|`:
//!
//!| a | s | d | f | g |
//!|---|---|---|---|---|
//!| h | j | k | l | ; |
//!
//! This table has space between the `//!` and the table start character `|`:
//!
//! | a | s | d | f | g |
//! |---|---|---|---|---|
//! | h | j | k | l | ; |
//!

If you remove the spaces, it works:

//! # Lorem ispum cratus test amet
//!
//!This table has no space between the `//!` and the table start character `|`:
//!
//!| a | s | d | f | g |
//!|---|---|---|---|---|
//!| h | j | k | l | ; |
//!
//! This table has space between the `//!` and the table start character `|`:
//!
//!| a | s | d | f | g |
//!|---|---|---|---|---|
//!| h | j | k | l | ; |
//!

I have made a example repo.
To test this, just clone the repo and run cargo doc --open
I have validated that this bug affects stable, beta and nightly

[camelid]

The reason this happens is that rustdoc needs to determine what indentation you're using in your doc comments, but you're mixing two different indentation levels, so it picks the smaller of the two (i.e., indent of zero). Thus, no indentation is stripped. Since Markdown doesn't recognize indented tables, the table that has a space before it is rendered wrong. If you instead use a consistent indentation level for each item's (i.e., each function, module, etc.) documentation, you'll see that the issue goes away. In other words, the following renders both tables correctly:

/// # Lorem ispum cratus test amet
///
///This table has no space between the `//!` and the table start character `|`:
///
///| a | s | d | f | g |
///|---|---|---|---|---|
///| h | j | k | l | ; |
///
pub fn foo() {}

/// # Lorem ispum cratus test amet
///
/// This table has space between the `//!` and the table start character `|`:
///
/// | a | s | d | f | g |
/// |---|---|---|---|---|
/// | h | j | k | l | ; |
///
pub fn bar() {}

I'm not sure if rustdoc can necessarily do better than this while respecting that different users may use different indentation levels for their doc comments. It's just like how Python doesn't allow you to mix 2-space and 4-space indentation or tab and space-based indentation in a file; there's no good way to disambiguate.

[camelid]

Note that the incorrect table rendering from the commit fed93af that linked to this issue is due to the incorrect double-comment //!//! at https://github.com/ALU-Schumacher/AUDITOR/blob/17aad52176ca0639c08082d981e79a5c2d293b91/auditor/src/lib.rs#L442. That incorrect syntax leads rustdoc to think the overall indentation of the block is zero. It's admittedly unfortunate that it's not obvious that this is the source of the issue.

One possible change we could consider is to base the indentation of the block on only the very first line. We could then report warnings if the indentation were less than that on later lines.

[camelid]

Another question is how we handle doc comments like the following

///     fn main() {}
pub fn foo() {}

Do we consider this to be the unindented text fn main() {}, or is it fn main() {} (a code block indented by 4 spaces), or is it fn main() {} (a code block indented by 4 spaces, whose content is in turn indented by 1 space)?

[camelid]

This was fixed in pulldown-cmark, so this now works correctly as of #127127.