"Go to Definition" and intra-doc links don't work properly for macro-generated code

[tamaro-skaljic]

Possible labels: A-macro, A-hover, A-goto-def, C-bug

---

Description

This issue builds upon the excellent work done in #503 and #4873 for resolving intra-doc links in hover documentation. While those changes successfully made intra-doc links work in cargo doc output, there are still significant limitations when working with macro-generated code in the IDE.

Current Problems

1. Go to Definition leads to macro instead of generated code

When using "Go to Definition" (F12) on symbols from macro-generated code, rust-analyzer navigates to the macro definition rather than showing the actual generated implementation. This makes it impossible to inspect the generated code directly in the IDE.

2. Intra-doc links in hover tooltips are not clickable

Even though intra-doc links are properly resolved and work in cargo doc, they appear as plain text in VS Code hover tooltips and cannot be clicked to navigate to the referenced items.

Current Workaround and Its Problems

To provide some visibility into the generated code, I've implemented an add_impl_doc function that includes the generated implementation as a code block in the documentation. However, this leads to extremely verbose documentation since the same implementation appears:

1. In the trait-level documentation
2. In the method-level documentation
3. As the actual implementation

This makes the documentation unwieldy and hard to read.

Expected Behavior

1. "Go to Definition" should work with generated code

• When using "Go to Definition" on macro-generated symbols, it should show the actual generated code, not just the macro
• Similar to how "Go to Definition" works with regular code, but for macro expansions
• Could be implemented as:
  • Direct navigation to generated code
  • An option in the "Go to Definition" context menu to choose between macro and generated code
  • Integration with the existing macro expansion features

2. Intra-doc links should be clickable in hover tooltips

• Intra-doc links in hover documentation should be clickable and functional
• When clicked, they should navigate to the referenced symbol (whether generated or not)
• This should provide the same navigation experience as cargo doc but within the IDE

3. Better macro code inspection

• Hover tooltips should show relevant generated code information
• Provide a way to inspect generated implementations without cluttering documentation

Technical Details

rust-analyzer version: (latest as of July 2025)
rustc version: 1.80+
editor: VS Code with rust-analyzer extension
repository: https://github.com/tamaro-skaljic/SpacetimeDSL

Related Issues

• Clickable links in markdown don't do anything #503 - "Clickable links in markdown don't do anything" (partially resolved)
• Resolve links in hover documentation #4873 - "Resolve links in hover documentation" (merged, but doesn't address IDE navigation)

Impact

This enhancement would significantly improve the developer experience for:

• Procedural macro authors who generate complex APIs
• Users of macro-generated code who need to understand the generated implementations
• Any project using extensive macro-generated code with documentation

The current limitations force developers to either:

• Use cargo doc --open constantly (breaking IDE workflow)
• Include verbose implementation details in documentation (cluttering docs)
• Work without proper code navigation (reducing productivity)

[jhgg]

This will be partially addressed by #19130 - in the interim you can just use the expand macro action with your cursor on the macro you wish to inspect.