libstd docs of re-exported macros are unformatted

[durka]

One example is the unreachable! macro, though I think I've seen it elsewhere. The documention of the macro in libcore is fine, but the docs of the same macro in libstd have the source formatting all weird, and the actual [src] link is broken.

[durka]

Of course you don't need the [src] link for a macro, but that's another issue!

[sfackler]

The formatting issue's a dup of #20923. Not sure if the src link being broken's been filed.

[durka]

The src link at the re-exported macro is gone, so closing.

[cbreeden]

I think this issue is relevant again. The solution for the dup was to refactor error reporting system, which doesn't solve the formatting issues in the docs.

[cbreeden]

I suspect that a quick solution to this problem may be to remove (or replace with ' ') all \n here https://github.com/rust-lang/rust/blob/master/src/librustdoc/clean/mod.rs#L2813.

At least it would put everything onto the same line.

[durka]

I don't think that's a great fix. I think the problem is that re-exported macros are stored into metadata in tokenized form, losing the original source formatting.

[QuietMisdreavus]

It looks more like that line you found is what prints each rule. Digging further, it seems to go through a ToSource trait which eventually calls span_to_snippet, which is where I would expect the formatting to come from.

[cbreeden]

I'm a little surprised that the highlighting doesn't work correctly, after looking at https://github.com/rust-lang/rust/blob/master/src/librustdoc/html/highlight.rs#L245. I don't believe there is much we can do about the formatting that comes from span_to_snippet given how macros are re-exported; though this might change once Macros 2.0 is here and so macros are given a bona fide path.

Until then I think the solution would be to manually handle the formatting given a TokenStream. Last night I was going to try to do some debugging to see why the $ formatting given in the docs above didn't trigger, but didn't get around to it.

[chordowl]

I ran across another manifestation of this today: the reexported version of Entry in std::collections::btree_map::Entry uses where clauses for lifetime bounds, while the original version of Entry in collections::btree_map doesn't; it seems like this is not strictly limited to macros.

[steveklabnik]

Triage: the formatting is still a bit strange; the src links work great though.

[jyn514]

I think this may be a duplicate of #36722.

[jyn514]

This is fixed on master.