Rustdoc changes code blocks to inline code in trait implementations

[nn1ks]

If a doc comment of a trait item begins with a code block, it will be changed to inline code in implementations of that trait, which leads to weird formatting.

Example

pub trait TraitExample {
    /// Some text.
    ///
    /// ```
    /// let a = 0;
    /// ```
    fn a() {}

    /// ```
    /// let b = 0;
    /// ```
    fn b() {}

    /// ```rust
    /// let c = 0;
    /// ```
    fn c() {}

    /// ```
    /// // Comment `example`.
    /// let d = 0;
    /// ```
    fn d() {}
}

pub struct StructExample;

impl TraitExample for StructExample {}

Here is what it looks like in the implementation for StructExample:

• The docs for the method a work as expected.

• The code block of method b is changed to inline code.

• The code block of method c is also changed to inline code and the word rust is shown in the inline code instead of specifying the syntax. There is also a trailing whitespace which is not present in the original code block.

• In the docs of d the backticks of the word example end the main inline code.

While the inline code looks fine in simple examples (e.g. docs of method b), the format is confusing in most cases. The expected behaviour would probably be that the code block does not get converted to inline code.

Example in std

Another example for this behaviour can be seen in the description method of std::error::Error. The docs of the method begin with a code block and then get changed to inline code in the implementations.

Documentation in std::error::Error:

Documentation of the implementation in std::io::Error:

More examples: std::io::Error (stable, nightly), std::num::ParseIntError (stable, nightly).

Meta

I ran rustdoc/cargo doc in both stable and nightly which all generated the same result.

rustdoc --version --verbose:

rustdoc 1.44.1 (c7087fe00 2020-06-17)
binary: rustdoc
commit-hash: c7087fe00d2ba919df1d813c040a5d47e43b0fe7
commit-date: 2020-06-17
host: x86_64-unknown-linux-gnu
release: 1.44.1
LLVM version: 9.0

rustdoc --version --verbose:

rustdoc 1.46.0-nightly (2935d294f 2020-06-17)
binary: rustdoc
commit-hash: 2935d294ff862fdf96578d0cbbdc289e8e7ba81c
commit-date: 2020-06-17
host: x86_64-unknown-linux-gnu
release: 1.46.0-nightly
LLVM version: 10.0