"[src]" links point to the place items are defined, not to the re-export

[vi]

https://docs.rs/remove_dir_all/0.2.0/remove_dir_all/fn.remove_dir_all.html

durka42 states that it's a bug in rustdoc and the entire doc is wrong.

[Mark-Simulacrum]

It seems like rustdoc is pulling the stdlib's source in instead of the crate's, but I'm not sure.

[durka]

It's getting the doc comments from std, too.

[ollie27]

rustdoc can only generate docs for one platform at once (#1998). I don't know what platform docs.rs uses by default but it's clearly not(windows). The docs for Windows seem fine: https://docs.rs/remove_dir_all/0.2.0/x86_64-pc-windows-msvc/remove_dir_all/fn.remove_dir_all.html.

[durka]

Aha so I was right and it *is* a re-export.

…

On Thu, May 11, 2017 at 12:10 AM, Oliver Middleton ***@***.*** > wrote: rustdoc can only generate docs for one platform at once (#1998 <#1998>). I don't know what platform docs.rs uses by default but it's clearly not(windows) <https://docs.rs/remove_dir_all/0.2.0/src/remove_dir_all/lib.rs.html#10-11>. The docs for Windows seem fine: https://docs.rs/remove_dir_ all/0.2.0/x86_64-pc-windows-msvc/remove_dir_all/fn.remove_dir_all.html. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#41903 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAC3n_NranGeEYe6QTOFz5zh3wlAKBhXks5r4oo4gaJpZM4NXbF0> .

[durka]

TRWTF is that rustdoc shows no indication at all that you're looking at re-exported docs.

…

On Thu, May 11, 2017 at 12:12 AM, Alex Burka ***@***.***> wrote: Aha so I was right and it *is* a re-export. On Thu, May 11, 2017 at 12:10 AM, Oliver Middleton < ***@***.***> wrote: > rustdoc can only generate docs for one platform at once (#1998 > <#1998>). I don't know what > platform docs.rs uses by default but it's clearly not(windows) > <https://docs.rs/remove_dir_all/0.2.0/src/remove_dir_all/lib.rs.html#10-11>. > The docs for Windows seem fine: https://docs.rs/remove_dir_all > /0.2.0/x86_64-pc-windows-msvc/remove_dir_all/fn.remove_dir_all.html. > > — > You are receiving this because you commented. > Reply to this email directly, view it on GitHub > <#41903 (comment)>, > or mute the thread > <https://github.com/notifications/unsubscribe-auth/AAC3n_NranGeEYe6QTOFz5zh3wlAKBhXks5r4oo4gaJpZM4NXbF0> > . >

[cuviper]

TRWTF is that rustdoc shows no indication at all that you're looking at re-exported docs.

That's probably "none of your business!" That is, the source crate is not pub exposed, so to users of this crate the function behaves as if it originated here. (Except you can probably test equivalence in other ways.)

[durka]

Yeah, but it's jarring when a [src] link suddenly takes you to another crate, so the facade breaks down anyway.

…

On Sat, May 13, 2017 at 7:02 PM, Josh Stone ***@***.***> wrote: TRWTF is that rustdoc shows no indication at all that you're looking at re-exported docs. That's probably "none of your business!" That is, the source crate is not pub exposed, so to users of this crate the function behaves as if it originated here. (Except you can probably test equivalence in other ways.) — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#41903 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAC3n-jUW5_OTrBV1UR49F3ZYBpzxefBks5r5jZzgaJpZM4NXbF0> .

[vi]

If the crate just re-exports another crate, I expect to see the re-export line when I click [src], unless it is some item inside the reexport.

[jyn514]

If the crate just re-exports another crate, I expect to see the re-export line when I click [src], unless it is some item inside the reexport.

Personally I would prefer not to do this - for something like futures::try_join that's re-exported from futures_util I don't think it makes sense to just show the re-export: this doesn't tell me anything about try_join! since futures_util isn't a well-known crate, all it makes me do is go to docs.rs/futures-util and try again from there with more clicks.

[jyn514]

This is the same as #22083, but for crates other than the standard library.

There are three ways rustdoc could behave:

1. All [src] links go to the place they're defined (the current behavior). If so both this issue and Rustdoc links to std library types can bypass the facade #22083 should be closed as wontfix.
2. libstd links go to the re-export, but all other links go to the place they're defined. If so this issue should be closed as wontfix and Rustdoc links to std library types can bypass the facade #22083 kept open. That behavior seems inconsistent to me - I guess we could add an attribute so users can configure it, but I don't like that we keep adding more and more knobs to rustdoc.
3. All links go to the re-export. If so Rustdoc links to std library types can bypass the facade #22083 should be closed as a duplicate of this issue. I don't know if I like this; it means it's hard to find where items come from.

For any of those, having both this issue and #22083 open isn't correct.

@rust-lang/rustdoc do you have opinions?

[GuillaumeGomez]

I'd be more inclined to link to the reexport but otherwise no strong feeling about it...

[Nemo157]

I don't necessarily agree that [src] and type/intra-doc links should behave the same. For facade's having the links to inlined re-exports allows control of the presentation of the docs, while using [src] normally means you want to actually see the source defining the type; and only the top-level [src] link could link to the re-export, all the other [src] links on the page (associated items, impls, etc.) can only link to the original definition, they have no actual source line in the re-export.

[CraftSpider]

I think option 1 is the way to go, [src] should always link to the place it's defined. For reasons similar to what Nemo just said, as well as my anecdotal opinion on how I use [src]: If I click it, I want to see the actual code. To click it and see a re-export would be immediately frustrating, and require putting in additional work to find what the link claimed by name to be giving me.

[jyn514]

I don't necessarily agree that [src] and type/intra-doc links should behave the same.

This is an excellent point. I agree [src] should go to the definition and "documentation" links should use the facade.