Closed
Description
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.
Metadata
Metadata
Assignees
Labels
Type
Projects
Milestone
Relationships
Development
No branches or pull requests
Participants
Activity
durka commentedon Jun 25, 2015
Of course you don't need the
[src]link for a macro, but that's another issue!sfackler commentedon Jun 25, 2015
The formatting issue's a dup of #20923. Not sure if the src link being broken's been filed.
durka commentedon Dec 16, 2015
The src link at the re-exported macro is gone, so closing.
cbreeden commentedon Jan 9, 2017
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.
[-]some macro docs are partly broken in libstd[/-][+]libstd docs of re-exported macros are unformatted[/+]cbreeden commentedon Jan 10, 2017
I suspect that a quick solution to this problem may be to remove (or replace with
' ') all\nhere 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 commentedon Jan 10, 2017
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 commentedon Jan 10, 2017
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 commentedon Jan 10, 2017
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_snippetgiven 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 commentedon Apr 13, 2017
I ran across another manifestation of this today: the reexported version of Entry in std::collections::btree_map::Entry uses
whereclauses 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 commentedon Oct 31, 2018
Triage: the formatting is still a bit strange; the src links work great though.
jyn514 commentedon Mar 25, 2021
I think this may be a duplicate of #36722.
jyn514 commentedon Apr 8, 2021
This is fixed on master.
