Markdown fails to be interpreted after #[doc] attribute is used

[SergioBenitez]

Consider the following structure with documentation:

/// Item docs.
///
#[doc="Hello there!"]
///
/// # Example
///
/// ```rust
/// // some code here
/// ```
pub struct NonGen;

At present, rustdoc will render this as:

Item docs.

Hello there!

# Example

// some code here

When the following is expected:

Item docs.

Hello there!

Example

// some code here

In short, after a #[doc] attribute, a markdown header is not interpreted as markdown.

This also applies to headers declared using ===, where

Example
=======

is rendered by rustdoc as:

Example =======

as opposed to the expected:

Example

I wouldn't be surprised if this is a more systemic issue and additional markdown syntax is interpreted literally as well.

[Havvy]

I would have expected that to be an error TBH.

[QuietMisdreavus]

A conversation on IRC (that i wasn't actually part of >_>) leads me to provide some background:

Rustdoc has a few passes it performs on doc comments before it hands the text to the markdown processor. The ones relevant to this discussion are collapse-docs (which combines multiple #[doc] attributes into a single body text) and unindent-comments (which strips leading indentation from the doc body text if every line has that same indentation).

The former is what @Havvy was thinking of, since it implies that rustc totally allows multiples of the same attribute on the same item. As a single /// doc comment desugars into a single #[doc=" doc comment"] attribute, this combines the attributes together into a single body of text that can be processed.

However, the latter is what is really at fault here. SpaceManiac on IRC suggested adding a leading space to the spliced-in doc attribute, and that allows the whole doc text to be handled correctly. Without that leading space there, unindent-comments sees a line with no leading indentation on it, and thus does not strip any leading spaces from the entire text. It's as if you were writing the text like this:

/// Item docs.
///
///Hello there!
///
/// # Example
///
/// ```rust
/// // some code here
/// ```
pub struct SomeStruct;

Note at the "Hello there!" line does not have a leading space on it.

I would assume that by the time rustdoc sees all the docs, it doesn't have any indication of whether the line came from a doc comment or a raw doc attribute. If the compiler has that information, then it may be possible to pass that over to rustdoc, which can then ignore "raw doc attributes" in the unindent-comments pass.

[GuillaumeGomez]

I'll take a look once I have enough time.