Clicking 'src' in rustdoc for a type defined by a macro should show invocation, not macro definition

[TedDriggs]

Repro steps:

1. Go to a type defined by a macro. Here's an example from Hyper.
2. Click "[src]" in the upper right

Expected: Open source viewer at the macro invocation which defines this type.
Observed: Open source viewer at the macro definition.

[durka]

It's kinda tricky. If the macro does several things and the links just take you to the invocation site, you don't get all the relevant information. Ideally you want both but I don't know how to UI that...

[TedDriggs]

I can imagine it's not easy (and I'd guess macros 1.1 makes it even more complex)

In an ideal world, it'd be great to see some sort of "macro preview" which would take you to the invocation and provide a way of seeing the expanded code from there.

An alternative would be - if the documenter knows that the type was declared in a macro - having the "src" option go to the invocation site and showing a link in the docs that says "declared in [macro]" which links to the macro's documentation.

[Mark-Simulacrum]

@rust-lang/dev-tools Looks like this needs a decision on what rustdoc should show in this case: Do we want some form of [expanded] link which takes the user to a (rustfmt-ated?) expansion of the macro.

[fitzgen]

I would personally expect to land at the macro invocation (or meta attribute for a custom derive macro).

It would also be great to be able to click on the macro from that view to jump to its definition (or some other equally ergonomic way to jump there), but that seems like a follow up issue to me.

Do we want some form of [expanded] link which takes the user to a (rustfmt-ated?) expansion of the macro.

This would be really neat (but again feels like a separate issue from this one). In general, I think the [src] links would be much more helpful if they were interactive like http://searchfox.org/ [0] and not static. I can imagine a world where some kind of [expanded] mode fit into that.

See also https://github.com/dtolnay/cargo-expand

[0] For example, try searching "js::SavedFrame" in searchfox. Click on the result showing the definition class SavedFrame : public NativeObject {. Check out how all the types of the members of that definition are links to those types' definitions. You can search by type/function definition, uses of types and functions, etc. It's a very interactive experience in comparison to [src] and I find it much more pleasant.

[nrc]

IMO, expanding macros is a bit beyond the scope of Rustdoc, at least for now (I have the vaguest of plans to make this work with save-analysis, etc.).

There is various info about the macro expansion in the span, so what can be displayed might be constrained by that. We should probably be able to follow errors, which try to 'do the right thing' for showing either macro definitions or invocations.

@fitzgen rustw does what you want, although does not have jump to def for macros at the moment. We might think, longer term, of integrating with rustdoc, but that is hard at the moment. If we power rustdoc from save-analysis it will be easier. I've also vaguely talked about integrating with searchfox, but that seems hard, likely they'll add there own Rust support but based off the same data as rustw.

[steveklabnik]

Traige: https://docs.rs/hyper/0.13.2/hyper/header/constant.ACCEPT_CHARSET.html is the best place to reproduce this bug

[jyn514]

Looks like this needs a decision on what rustdoc should show in this case: Do we want some form of [expanded] link which takes the user to a (rustfmt-ated?) expansion of the macro.

FWIW, both @GuillaumeGomez and I agreed this would be a great improvement to rustdoc.

[jyn514]

Ideally you want both but I don't know how to UI that...

In an ideal world, we'd have go-to-definition in the source viewer ... but that's a much larger project.

[GuillaumeGomez]

In an ideal world, we'd have go-to-definition in the source viewer ... but that's a much larger project.

Both are kinda independent, but having go-to-definition would definitely be a huge improvement for the doc sources overall. That's in loooooong TODO list and I hope to be able to get to it at some point.