rustdoc does not link correctly within first-line (descriptions)

[chriskrycho]

There are times it's nice to be able to include a link in the description of a given item. At present, however, if you try to include a reference link, it fails.

Rust:

/// Describe it. [Link somewhere][1].
///
/// [1]: http://www.rust-lang.org/
pub fn here_is_a_fn() { }

HTML for the item description:

<td class="docblock short">
     <p>Describe it. [Link somewhere][1].</p>
</td>

However, if you change the first line of the Rust to be an inline reference, the problem goes away. Rust:

/// Describe it. [Link somewhere](http://www.rust-lang.org/).

Generated HTML:

<td class="docblock short">
     <p>Describe it. <a href="http://www.rust-lang.org/">Link somewhere</a>.</p>
</td>

It appears (I haven't had a chance to check the implementation yet) that rustdoc is only parsing the first Markdown block element, rather than only keeping the first block element. This probably slightly improves performance, but it produces unexpected results.

[mitaa]

-> #25787