rustdoc: fix summary lines

[mitaa]

fixes #31899

r? @alexcrichton

[mitaa]

cc @bluss

[bluss]

Response time is A+++ 😄

[mitaa]

I just remembered that this function is also used for the search-index descriptions, which are not markdown rendered. So that still needs the old behaviour.

I'm going to push an update as soon as I have time.

[alexcrichton]

The idea here was to render headers like:

/// really long intro
/// comment
///
/// more explanation

as "really long intro comment", but doesn't this break that as only the first line is taken?

[mitaa]

You're right, I guess I got a bit confused by looking at the HTML source through inspector, which doesn't show the newlines in the <p> element (I thought hoedown/markdown removes these).
The rendererd markdown for

/// A tuple or fixed size array that can be used to index an array.
/// Make this line a bit longer.
///
/// ```
/// use ndarray::arr2;
/// ```
pub fn bar() {}

actually is

<p>A tuple or fixed size array that can be used to index an array.
Make this line a bit longer.</p>
<pre class='rust rust-example-rendered'>
<span class='kw'>use</span> <span class='ident'>ndarray</span>::<span class='ident'>arr2</span>;</pre>

Because of this I'm now extracting the first occuring html element in the string which seems to me the correct way to go.
I don't think that there is something in-tree with which I could replace the parsing code I've written?

[alexcrichton]

Er hang on, can we drill into what the bug is in the first place? I'd really like to avoid having any sort of HTML parser in rustdoc just to extract the first <p> span or something like that, it sounds quite brittle!

It looks like the bug may be that we're extracting text after rendering, when we should be extracting before rendering?

[mitaa]

I'm a bit uneasy about the parsing, but extracting before rendering means reintroducing #30366 and #25787.

[mitaa]

The problem doesnt appear with two paragraps, but with one paragraph and a codeblock. Specifically hoedown doesnt leave a blank line in this case.

..perhaps we could insert a dummy item between the first and second block, which we know leaves a blank line, before we markdown render it? (and then shorten it after rendering)

/// A tuple or fixed size array that can be used to index an array.
/// Make this line a bit longer.
///
/// # dummy
/// ```
/// use ndarray::arr2;
/// ``````

[alexcrichton]

Can we perhaps alter the hoedown rendering of code blocks to insert the blank line for us? That may be a good fix in the case that code blocks are the only cause of this.

[mitaa]

Oh right, we can do that 😄

(updated)

[alexcrichton]

@bors: r+ 0b3bc9b

Thanks!

[bors]

⌛ Testing commit 0b3bc9b with merge 095f5e7...

[bors]

☀️ Test successful - auto-linux-32-nopt-t, auto-linux-32-opt, auto-linux-64-debug-opt, auto-linux-64-nopt-t, auto-linux-64-opt, auto-linux-64-x-android-t, auto-linux-cross-opt, auto-linux-musl-64-opt, auto-mac-32-opt, auto-mac-64-nopt-t, auto-mac-64-opt, auto-mac-ios-opt, auto-win-gnu-32-nopt-t, auto-win-gnu-32-opt, auto-win-gnu-64-nopt-t, auto-win-gnu-64-opt, auto-win-msvc-32-opt, auto-win-msvc-64-opt

[bluss]

Thank you @mitaa !