[rustdoc] intra-doc links for macros always resolve relative to the crate root

[Lokathor]

If you have a function defined within a module it will use that module's imports to determine link resolution for intra-doc links in the documentation.

If you do the same with a macro, it seems to "scope" the macro (and thus its intra-doc links) at the crate root only, so the macro's documentation can't benefit from the local imports.

This feels inconsistent, and can it be fixed so that macro intra-links get the local imports for their resolution?

[jyn514]

it seems to "scope" the macro (and thus its intra-doc links) at the crate root only,

Isn't this expected behavior? Macros are always moved up to the crate root.

[Lokathor]

Logically, within the crate's namespace, yes, the macro will appear in the crate root.

However, it makes editing the docs of the macro worse because the macro's actual location is still whatever file it's written in, not always lib.rs. Every other item's docs use the local file's imports to determine intra-doc links.

[jyn514]

Technically they use the imports of the parent module, not the imports of the current file. I'm sympathetic to this use case but I'm not sure how feasible it is to implement, by the time rustdoc resolves intra-doc links we've lost the lexical scope and we're left with only the DefId (resolution scope): https://github.com/rust-lang/rust/blob/master/src/librustdoc/passes/collect_intra_doc_links.rs#L428

[jyn514]

@rustbot modify labels: C-enhancement

[Lokathor]

Well if it can't be done it's ultimately fine, it just hit me as a weird detail on a crate that has many macros which must be kept in many separate files.

[jyn514]

I'm not sure how feasible it is to implement, by the time rustdoc resolves intra-doc links we've lost the lexical scope and we're left with only the DefId

After #77519 this is no longer true; I don't think we currently store the scope if it's not a re-exports, but it shouldn't be too hard to add. So this changes to a question of whether we should change it.

@Manishearth what do you think?

[Manishearth]

@jyn514 I don't have a strong opinion here

[jyn514]

Since intra-doc links are already stable, and since this is following the same rules of the language, we do not plan to change the behavior here.

[ChrisDenton]

In that case, is there a way to force linking to a macro in a specific path instead of resolving to the crate root? I'm finding it makes some docs weird when the text says one thing but the link goes somewhere else.