Tracking Issue for intra-doc links in libstd · Issue #75080 · rust-lang/rust (original) (raw)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Description

This is a tracking issue for switching libstd to intra-doc links (rust-lang/rfcs#1946, #74430 (comment)).

About tracking issues

Tracking issues are used to record the overall progress of implementation.
They are also uses as hubs connecting to other relevant issues, e.g., bugs or open design questions.
A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature.
Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.

Mentoring instructions (or rather, suggested workflow)

Please first leave a comment here stating that you want to work on file xxx.rs or module xxx, to make sure that this implements Sync.

For each link of the form

rewrite it as

[`Type`]: std::module::Name::foo

In most cases, the type will already be in scope, in which case you can remove the reference link altogether.
For an example PR, see #74470.

Run x.py doc library/std. This should warn(broken_intra_doc_links) by default.
Fix any warnings that appear.
Once you are ready to make a PR, run ./x.py tidy, which will run rustfmt.

In case of rustdoc bugs, there may be broken links that didn't show up when you ran x.py doc. However, these will be caught by the test suite, so you don't have to check them locally.

Suggested tools

@poliorcetics wrote a python script which can automate much of the conversion: Tracking Issue for intra-doc links in libstd #75080 (comment)
@denisvasilik wrote a regex which matches links in core and std: Tracking Issue for intra-doc links in libstd #75080 (comment)
@RDambrosio016 came up with several different regexes, starting around Tracking Issue for intra-doc links in libstd #75080 (comment)

Caveats

~~Primitives that have the same name as a module in scope must use type@ to disambiguate them. For example, to link to char from std, use type@char.~~ This was changed in #75318, char will now link to the primitive, not the module.

The following cannot use intra-doc links. If you run into an issue with them, it's ok to skip them. However, if you see an issue not mentioned here, please file a bug report!

Some primitives (notably slices and pointers): Intra-rustdoc links do not work for all primitives #63351, Intra-doc links do not resolve for value keywords #74515
Links from core to std (Figure out a way to link to downstream crates #74481)
Documentation is also tested with --stage 0, so you may not be able to make changes that require recently merged fixes: Move to doc links inside the prelude #75368 (comment)
~~Associated items anywhere other than documenting the associated item itself (Fix intra-doc links for associated items #74489)~~ Fixed
Links on default function implementations for a trait (Intra-doc links are not resolved in inherited docs from upstream traits #73829). Note that these will not warn if they fail to resolve, so you should be careful about modifying links on traits. Fixed

TODO list

This list was generated with rg '\[.*\]: \.\./.*' library/ -l | sed 's/^/- [ ] /' and may not be complete. If you see other links not mentioned here, feel free to fix them as well.

Since most files only have a few links, it's fine to claim multiple files at the same time.

Cannot be fixed

The following links cannot yet be fixed due to limitations in rustdoc.

[Vec::get_mut] (Move to intra-doc links for task.rs and vec.rs #75672 (comment))