Relative URL in doc comments

Hello all, I noticed a problem in the doc comments of the Rust libraries, with many links to HTML pages were relative URLs. For instance in library/core/src/ops/, for Deref:

/// For more details, visit [the chapter in *The Rust Programming Language*][book]
/// as well as the reference sections on [the dereference operator][ref-deref-op],
/// [method resolution] and [type coercions].
/// [book]: ../../book/ch15-02-deref.html
/// [more]: #more-on-deref-coercion
/// [ref-deref-op]: ../../reference/expressions/operator-expr.html#the-dereference-operator
/// [method resolution]: ../../reference/expressions/method-call-expr.html
/// [type coercions]: ../../reference/type-coercions.html

Those relative links are a problem for (some?) IDEs

With the IntelliJ pluging, they lead to a generic and irrelevant page, with Visual Studio Code they trigger a pop-up error, and I suppose I'm not the only one having this problem. They actually seem to work on the website only, since those paths are relative to its base URL. We see for example here that

/// [type coercions]: ../../reference/type-coercions.html

is meant to open

and that

/// [book]: ../../book/ch15-02-deref.html

is meant to open

Is it fixable?

A basic search showed some 327 matches in the Rust library, in the repository. I first thought a systematic replace could be done, but I suspect that the relative paths are there for a reason, maybe to vary with stable/nightly releases or the current branch being worked on with some specific setup?

I can replace those links as a pull request, but I'd rather ask first if it's worth it ... or potentially breaking.

Making them absolute paths would break offlinw docs. Instead I think rust-analyzer should rewrite the links.


Also presumably relative links make supporting the unversioned, the channel based and the version number based easier.


Maybe a good suggestion for the different tools then.

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.