Rustdoc allows linking to std elements either directly by name [IntoIterator] or explicitly disambiguated [IntoIterator](std::iter::IntoIterator).
The hover and in-IDE links from rust-analyzer suggest that the links I have in place all work fine.
But when I build the docs locally to verify in a browser (both with or without --no-deps), the links don't render. The first shows as [IntoIterator], the second as IntoIterator (which points to an invalid url)
Is there any way to get cargo doc to build the local docs and place valid links to the online stdlib docs? All the RFCs, forum posts etc I could find were about using a locally hosted version of stdlib docs and I can't see how to bend any of them to this need.
I can't reproduce the behavior, the generated doc contains a valid link to doc.rust-lang.org.
how did you install the rust toolchain, is it installed via rustup or from your operating system package manager? if rustup, what's the profile or components being installed? e.g. what's the output of rustup component list --installed?
rust is installed via rustup
docs generated with cargo doc
served locally with cargo server --path target/doc
viewed at 127.0.0.1:8000/cratename
it's also reproducible (blazingly slowly github.com/MusicalNinjaDad/try_v2:
cargo doccargo server --path target/docclick the link to the forwarded port 8000
extend the uri to the page /try_v2/derive.IntoIterator.html
see links in first sentence
I've not published this version yet, so there is a chance I did something blazingly stupid when updating the docs myself and they won't render on docs.rs either ... but if I did, I really can't see it
I cloned your repo and find the problem is related to re-exported procedural macro.
the links work fine when you visit the documentation of the try_v2_derive crate, but they broke on the page of the re-exported item in the try_v2 crate.
I don't know if this is a known bug, a quick search found these similar titles, but I don't think they are actually related to your case.
opened 11:53AM - 02 Jun 26 UTC
T-rustdoc
C-bug
needs-triage
# Code
https://www.chiark.greenend.org.uk/ucgi/~ian/git?p=rust-experiments.git;… a=shortlog;h=refs/heads/rustdoc-link-2026-06
# Reproduction Steps
```
git clone https://www.chiark.greenend.org.uk/ucgi/~ian/githttp/rust-experiments.git -b rustdoc-link-2026-06
cd rust-experiments
cargo doc --workspace --all-features --document-private-items
```
# Expected Outcome
```
warning: unresolved link to `later`
```
# Actual Output
No errors, but documentation has a broken link. To see the broken link:
1. In your browser, visit the local path printed by the rustdoc rune
2. Click on the entry for the macro `earlier` ~~`derive_deftly_template_Earlier`~~
3. Click on the word "Reference" (which is the start of the body of the doc comment)
4. You're now visiting a file `.../rust-experiments/target/doc/foo/later` which does not exist
# Version
```
rustdoc 1.96.0-beta.5 (a5a9a5438 2026-05-01)
```
# Additional Details
## Ordering is relevant
AFAICT the link is not resolved because it's a forward reference to a macro_rules macro. Swapping the definition of `later` to before `Earlier` makes the link resolve.
## Exporting is ~~might be~~ relevant
Adding `#[macro_export]` to the definitions (via the `export` keyword to the derive-deflty call if necessary) makes it work.
~~But with the MCVE, it doesn't seem to make any difference.~~
## Either spans, or merely the involvement of a proc macro, seem to be relevant
Update: for a repro without any external crates, see below.
~~I was not able to reproduce this without derive-deftly.~~ The `define_derive_deftly` call in `lib.rs` expands to this:
```
#[doc = " Doc comment"] #[doc = ""] #[doc = " [Reference](later)"]
#[doc =
"\n\nThis is a `derive_deftly` template. Do not invoke it directly.\nTo use it, write: `#[derive(Deftly)] #[derive_deftly(Earlier)]`."]
macro_rules! derive_deftly_template_Earlier
{
[ actual macro body elided for clarity ]
}
```
You can get that output yourself with a rune like this:
`RUSTFLAGS="--cfg derive_deftly_dprint" DERIVE_DEFTLY_DPRINT=1 cargo doc --workspace --all-features --document-private-items`
But, when I replace the `define_derive_deftly!` call with a cut-and-paste of the whole expansion (as printed via the `TokenStream`'s `Display` impl) the bug goes away: I get the warning as expected.
I experimented with replacing the `define_derive_deftly` call with a macro_rules macro whose expansion was a c&p of the derive-deftly output, but that also didn't repro the bug.
It may be relevant that for Reasons, derive-deftly respans its output using `.resolved_at(Span::call_site)` . For terminal TTs it then uses `.set_span()`. For groups it must use `Group::new` (via `proc_macro2::Group::new`). The precise code can be seen here https://gitlab.torproject.org/Diziet/rust-derive-deftly/-/blob/03493e38977328ce1cfd89bad38a868538479419/macros/utils.rs#L200
However, I don't think any of this should cause rustdoc to emit HTML containing broken links.
opened 08:22PM - 08 Feb 21 UTC
T-rustdoc
C-bug
A-cross-crate-reexports
*[View all comments](https://triagebot.infra.rust-lang.org/gh-comments/rust-lang… /rust/issues/81893)*
I have a macro crate with a "peer dependency" on another crate, i.e. I can't write doctests for the macro itself without introducing circular dev-dependencies which are kind of annoying. The other crate re-exports the macro and the macro is actually expected to only ever be used through there, so I documented the re-export instead. However, there's another higher-level crate that re-exports a bunch of other crates entirely including the one that re-exports the macro. In the documentation of the higher-level crate, the documentation for the macro does not appear, while it appears on the "level-one" re-export.
Minimal reproduction:
Crate foo re-exports a type from bar, which is itself a re-export of a type from baz. The docs on each of the declarations (original type definition in `baz`, re-exports in `bar` and `foo`) are simply the crate name
```rust
// # baz/src/lib.rs
/// baz
pub struct Type;
// # bar/src/lib.rs
/// bar
pub use baz::Type;
// # foo/src/lib.rs
/// foo
pub use bar::Type;
```
Here is a repo with this: https://github.com/jplatte/rust-issue-81893
I expected to see this happen: the docs of `foo::Type` should be `foo bar baz`
Instead, this happened: the docs of `foo::Type` are `foo baz`
### Meta
Happens with latest nightly from rustup that has rustfmt:
`rustc --version --verbose`:
```
rustc 1.51.0-nightly (04caa632d 2021-01-30)
binary: rustc
commit-hash: 04caa632dd10c2bf64b69524c7f9c4c30a436877
commit-date: 2021-01-30
host: x86_64-unknown-linux-gnu
release: 1.51.0-nightly
LLVM version: 11.0.1
```
maybe open a new bug report if it has not been reported yet.
Thanks I hadn't spotted that. I've just published v0.10.0 and the same occurs on docs.rs - it looks like a bug / limitation in rustdoc so I'll look at opening an issue or adding to an existing one
for future people finding this via a search ...
opened 04:46PM - 09 Jul 26 UTC
T-rustdoc
C-bug
needs-triage
# Code
in crate1:
```rust
/// Derives [`IntoIterator`](std::iter::IntoIterator… ) analog to [Result] & [Option].
#[proc_macro_derive(IntoIterator)]
pub fn into_iterator(input: TokenStream1) -> TokenStream1 {
...
}
```
in crate2:
```rust
/// Methods for transforming TryTypes. Inspired by the methods provided on [`Option`] & [`Result`](std::result::Result)
pub trait Transform<T> {
...
}
```
in crate0:
```rust
#[doc(inline)]
pub use crate1::*;
#[doc(inline)]
pub use crate2::*;
```
# Reproduction Steps
- [re-export of crate1](https://docs.rs/try_v2/0.10.1/try_v2/derive.IntoIterator.html) - :x: **does not** render links to `IntoIterator`, `Option`, `Result`
- [direct docs for crate1](https://docs.rs/try_v2_derive/0.10.1/try_v2_derive/derive.IntoIterator.html) - :white_check_mark: does render links to `IntoIterator`, `Option`, `Result`
- [re-export of crate2](https://docs.rs/try_v2/0.10.1/try_v2/trait.Transform.html) - :white_check_mark: does render links to `Option`, `Result`
- [direct docs for crate2](https://docs.rs/try_v2_traits/0.10.1/try_v2_traits/trait.Transform.html) - :white_check_mark: does render links to `Option`, `Result`
# Expected Outcome
Links should be rendered on re-export of derive macros just as they are on re-export of traits
# Version
1.98.0-nightly
This appears to only be for derive macros / possibly for all proc_macros and does not occur for similarly re-exported traits.
) in a codespace at