regression 1.49: rustdoc runs indented documentation immediately after a header as a doctest

[Mark-Simulacrum]

• https://crater-reports.s3.amazonaws.com/beta-1.49-1/beta-2020-11-26/gh/bes.google-datastore1-generated/log.txt

My guess is that rustdoc's behavior on parsing doc attributes has changed or something like that -- I recall seeing a PR changing how we handle things. Maybe for example previously \n in an attribute worked and now doesn't?

cc @rust-lang/rustdoc

[jyn514]

Is there a way to see the full source for this? The error sounds like it's a doctest or something, not documentation directly.

[Mark-Simulacrum]

It's a public repo, https://github.com/bes/google-datastore1-generated/blob/master/src/lib.rs#L1

[Mark-Simulacrum]

https://crater-reports.s3.amazonaws.com/beta-1.49-1/beta-2020-11-26/reg/auto-0.0.8/log.txt might also be related (that one is on crates.io)

[jyn514]

The bug is that this is being interpreted as a doctest instead of normal documentation. Not sure why yet.

[Mark-Simulacrum]

https://crater-reports.s3.amazonaws.com/beta-1.49-1/beta-2020-11-26/reg/glutin-0.25.1/log.txt also seems to do the same

edit: and

• https://crater-reports.s3.amazonaws.com/beta-1.49-1/beta-2020-11-26/reg/initial_conditions-0.4.0/log.txt
• https://crater-reports.s3.amazonaws.com/beta-1.49-1/beta-2020-11-26/reg/ruckus-2d-0.1.1/log.txt
• https://crater-reports.s3.amazonaws.com/beta-1.49-1/beta-2020-11-26/reg/tox_encryptsave-0.1.0/log.txt

[jyn514]

I think this was fa1b15f.

[jyn514]

MCVE:

//!# Header
//!    x

Stable ignores it, beta runs x as a doctest.

[jyn514]

For context,

//!# Header
//!
//!    x

is run on a doctest on stable. So maybe newlines are getting discarded somewhere?

[jyn514]

searched toolchains nightly-2020-10-01 through nightly-2020-12-01


********************************************************************************
Regression in nightly-2020-11-05
********************************************************************************

fetching https://static.rust-lang.org/dist/2020-11-04/channel-rust-nightly-git-commit-hash.txt
ERROR: Tarball not found at https://static.rust-lang.org/dist/2020-11-04/channel-rust-nightly-git-commit-hash.txt

I confirmed locally that reverting #78400 fixes the issue.

cc @GuillaumeGomez

[GuillaumeGomez]

It's because the header starts with //!# Header. Because there is no space before //!, everything is aligned to this, making //! x a doctest because there are 4 spaces. So this is the expected behavior, it was just buggy before. :)

[rylev]

@GuillaumeGomez can you clarify why this is expected behavior (not sure I fully follow your explanation above). This seems very unexpected to me.

[GuillaumeGomez]

So I wrote a whole blog post explaining this change here. TLDR:

Since the minimum indent is "0" because of //!# Header (where there is no whitespace before #), the line //! x has an indent of 4, making it a code block based on the markdown spec.

If you don't want x to be a code block, add a whitespace before # Header or remove a whitespace from //! x.

[Mark-Simulacrum]

Will close as won't fix, but we should include in release notes.

[Mark-Simulacrum]

@XAMPPRocky Can we add an entry to the 1.49 release notes for this issue? It sounds like roughly

• Leading whitespace is stripped more uniformly in documentation comments, which may change behavior. Read this post for more details.

[GuillaumeGomez]

That'd be a good idea indeed!

[XAMPPRocky]

Closing, as it's now in relnotes.