Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

rustdoc: broken "src" link #15309

Closed
noamraph opened this issue Jul 1, 2014 · 3 comments
Closed

rustdoc: broken "src" link #15309

noamraph opened this issue Jul 1, 2014 · 3 comments
Assignees
Labels
T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@noamraph
Copy link
Contributor

noamraph commented Jul 1, 2014

In http://doc.rust-lang.org/std/sync/struct.Arc.html
click "src". It links to http://doc.rust-lang.org/alloc/arc/struct.Arc.html?gotosrc=1343 which is forwarded to http://doc.rust-lang.org/alloc/arc/undefined

@Gankra
Copy link
Contributor

Gankra commented Aug 26, 2014

@alexcrichton Is there any historical or technical reason for suffixing [src] link id's with a unique numeric code? Stripping that would solve this problem. Although this might be a symptom of a larger rustdoc bug that should ultimately be fixed.

@Gankra
Copy link
Contributor

Gankra commented Aug 26, 2014

After some minor sleuthing and discussion with acrichto, this is what I know.

  • The bug is caused by the reexported crate yielding the wrong magic number in the ?gotosrc=xxx argument.
  • The ?gotosrc=xxx argument tells rustdoc's JS to find a link on the page with id #src-xxx, and open the link.
  • The reason the suffix exists is to support multiple [src] URLs on the same page, which is desired for the future.
  • See src/librustdoc/html/static/main.js#732 for the JS logic
  • See src/librustdoc/html/static/main.js#1264 for where the gotosrc number is written

From the latter we can see that this number is extracted from a fairly deep hierarchy of objects. self is an Item as defined in this module, from which we are extracting a clean::Item, from which we are extracting a syntax::ast::DefId, from which we are extracting a NodeId, which is just a u32. It is unclear where in this process the incorrect id is set (or perhaps the incorrect Item/DefId).

Unfortunately I'm out of my depth, and have other pressing matters at hand. As a shim to get correct behaviour, we could simply remove this unique id business until we actually need to support multiple [src] links.

@lifthrasiir
Copy link
Contributor

I've analyzed this issue and this seems to be a fundamental problem with using DefId in the documentation. In the other words...

We should never use DefIds in the documentation because THEY WOULD CHANGE!

For liballoc we used to pass --cfg jemalloc to rustc but not to rustdoc, so we were actually working with different ASTs. A fix on Makefiles or even #2206 may avoid this issue (as we are looking at the same AST then) but they are not a definite solution. I'll work on the patch which removes all uses of DefIds from generated docs.

lifthrasiir added a commit to lifthrasiir/rust that referenced this issue Dec 6, 2014
This commit uses an existing foreign inlining facility to implement
the doc generation from compiled crates. At the highest level,
this is a *huge* hack since the metadata doesn't provide everything
we need to generate docs.

Fixes rust-lang#2206. Will fix rust-lang#15309 once integrated with Makefile.
@alexcrichton alexcrichton self-assigned this Apr 7, 2015
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants