rustdoc never closes a list

[whitequark]

Consider this comment:

//!  * First, it provides functions to extract fields from sequences of octets,
//!    and to insert fields into sequences of octets. This happens through the `Frame`
//!    and `Packet` families of structures, e.g. [EthernetPacket](struct.EthernetPacket.html).
//!  * Second, in cases where the space of valid field values is much smaller than the space
//!    of possible field values, it provides a compact, high-level representation
//!    of packet data that can be parsed from and emitted into a sequence of octets.
//!    This happens through the `Repr` family of enums, e.g. [ArpRepr](enum.ArpRepr.html).
//!
//! The functions in the `wire` module are designed for robustness and use together with
//! `-Cpanic=abort`. The accessor and parsing functions never panic. The setter and emission
//! functions only panic if the underlying buffer is too small.

There is no way to make rustdoc not add the third paragraph, and everything that follows, into the 2nd list item.

[whitequark]

Workaround: add a </ul> explicitly.

[pyfisch]

Cannot reproduce on rustc 1.16.0-nightly (4ecc85beb 2016-12-28). Anyway try removing one space character before the list items.

[whitequark]

That didn't help. I am using rustc 1.15.0-nightly (daf8c1dfc 2016-12-05).

[whitequark]

@pyfisch I can reproduce this on rustc 1.16.0-nightly (4ecc85beb 2016-12-28) as well. Please check out https://github.com/m-labs/smoltcp/tree/c104859011d8393fe3fdcf8ad54381ea6e055707 and remove this line: https://github.com/m-labs/smoltcp/blob/c104859011d8393fe3fdcf8ad54381ea6e055707/src/wire/mod.rs#L13.

[pyfisch]

@whitequark Indeed. Use line comments (//! ...) instead of block comments (`/*! ... */) in line 27 to 45 and the list is closed.

[whitequark]

@pyfisch The ergonomics of that is absolutely atrocious for code examples, so I'm not going to. I don't see a reason for rustdoc to exhibit this "action at a distance"; why does a comment way below affect the way a list is closed?

[pyfisch]

This is obviously a bug in rustdoc.

why does a comment way below affect the way a list is closed?

I don’t know the inner workings of rustdoc an I am not inclined to research this edge case related to uncommon doc-comment syntax. Maybe you can find the problem yourself in the code?

[GuillaumeGomez]

Taking a look.

[QuietMisdreavus]

This is the same issue as #42760: The code within the /*! block does not have the same indentation as the /// lines before it. Thus, the unindent-comments pass does not strip the leading spaces from the first section. Hoedown gets confused when the stuff after the list isn't completely unindented, so it just gloms all that onto the list. To fix that sample, you can shift everything in the /*! block over by one space.

Some good news, though? The new Pulldown renderer is more strict about what items are part of list items, so it does what you want it to here. (cc #44229)

[kzys]

Resolving?

[GuillaumeGomez]

I removed lists iirc so yes definitely.