[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

[jhpratt]

Not sure if this is related, but when reëxporting a macro from another crate, the path isn't always correct even when explicitly specified. I have the macros exported through both the macros and prelude modules, but only have it documented in the former (the latter is a reëxport of the former, but documentation doesn't indicate it as such?). As rustdoc doesn't get the right path during the documentation of the contents of the macro module, I added an explicit [`time!`]: crate::macros::time in an attempt to get it to resolve correctly; unfortunately it still resolves to the already-wrong documentation in the prelude module.

Ultimately this is probably just a problem with macros 1.0 in general, and the newer (unstable) macro syntax and path handling might already have this handled correctly.

[jyn514]

@jhpratt I'm not 100% following - can you make an MCVE?