Tracking Issue for intra-doc links in libstd

[jyn514]

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.

1. For each link of the form

[`Type`]: ../../std/module/kind.Name.html#method.foo

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.

2. Run x.py doc library/std. This should warn(broken_intra_doc_links) by default.
3. Fix any warnings that appear.
4. 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.

Unclaimed

• [std::convert::identity]: crate::convert::identity (Move to intra-doc links for /library/core/src/hint.rs #75423 (comment))
• [i32::MAX] (Fix intra-doc links for associated constants on primitives #76093)
• [crate::ptr] in libcore (intra-doc links: crate::ptr on a re-export of core::slice is not resolved in alloc #76106)
• [TcpStream::read]: Read::read (Move to intra doc links for std::io #75674)

In-progress

• library/core/src/num/mod.rs (Claimed by @jyn514 in Tracking Issue for intra-doc links in libstd #75080 (comment))
• [flush]: Write::flush (https://github.com/rust-lang/rust/pull/75674/files#diff-1eb455549b75a568d81f2f6a8a7020c0R446, claimed by @pitaj in Tracking Issue for intra-doc links in libstd #75080 (comment))
• floating point methods in intrinsics (see description of Move to intra-doc links for /library/core/src/intrinsics.rs #75705, claimed by @pitaj in Tracking Issue for intra-doc links in libstd #75080 (comment))

Completed

• library/core/src/str/mod.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/time.rs (claimed by @denisvasilik)
• library/core/src/cmp.rs (claimed by @denisvasilik)
• library/core/src/borrow.rs (claimed by @denisvasilik)
• library/std/src/path.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/os/*/fs.rs (Claimed by @nixphix in Tracking Issue for intra-doc links in libstd #75080 (comment)). Note that the PR is only a partial fix since there are associated items that cannot be fixed until Fix intra-doc links for associated items #74489 is merged.
• library/std/src/time.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/prelude/mod.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/io/mod.rs (Claimed by @camelid in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/lib.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/ffi/*.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/os/raw/*.md (Claimed by @nixphix in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/net/*.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/sys/windows/ext/fs.rs (Claimed by @nixphix in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/sys/windows/ext/process.rs (Claimed by @nixphix in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/sys/windows/ext/ffi.rs (Claimed by @nixphix in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/process.rs (Claimed by @camelid in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/option.rs (Claimed by @camelid in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/mem/manually_drop.rs (claimed by @chansuke)
• library/core/src/mem/maybe_uninit.rs (claimed by @chansuke)
• library/core/src/hint.rs (Claimed by @denisvasilik in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/panic.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/ascii.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/fs.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/any.rs (Claimed by @denisvasilik in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/char/convert.rs (Claimed by @denisvasilik in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/sys/vxworks/ext/process.rs (Claimed by @nixphix in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/sys/vxworks/ext/fs.rs (Claimed by @nixphix in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/error.rs (Claimed by @ellennyan in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/alloc.rs (Claimed by @ellennyan in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/env.rs (Claimed by @ellennyan in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/keyword_docs.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/io/buffered.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/io/cursor.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/io/error.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/io/util.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/sys/unix/ext/fs.rs (Claimed by @nixphix in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/sys/unix/ext/thread.rs (Claimed by @nixphix in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/sys/unix/ext/process.rs (Claimed by @nixphix in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/sys/unix/ext/net.rs (Claimed by @nixphix in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/result.rs (Claimed by @camelid in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/thread/mod.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/thread/local.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/alloc/src/task.rs (Claimed by @kofls in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/alloc/src/vec.rs (Claimed by @kofls in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/intrinsics.rs (Claimed by @denisvasilik in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/alloc/src/macros.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/alloc/src/rc.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/alloc/src/sync.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/alloc/src/lib.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/alloc/src/string.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/alloc/src/collections/linked_list.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/alloc/src/slice.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/alloc/src/alloc.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/alloc/src/fmt.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/alloc/src/boxed.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/str/pattern.rs (Claimed @GuillaumeGomez in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/ops/deref.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/ops/index.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/ops/function.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/ops/drop.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/ops/unsize.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/ops/mod.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/ops/arith.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/ops/range.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/sync/mutex.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/sync/rwlock.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/sync/condvar.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/sync/mpsc/mod.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/alloc/global.rs (Claimed by @denisvasilik in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/alloc/mod.rs (Claimed by @denisvasilik in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/alloc/layout.rs (Claimed by @denisvasilik in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/raw.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/ffi.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/pin.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/os/illumos/fs.rs (Claimed by @camelid in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/os/openbsd/fs.rs (Claimed by @camelid in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/macros.rs (Claimed by @camelid in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/array/mod.rs (Claimed by @camelid in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/char/mod.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/macros/mod.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/fmt/mod.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/proc_macro/src/lib.rs (Claimed by @LeSeulArtichaut in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/collections/mod.rs (Claimed by @camelid in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/future/future.rs (Claimed by @camelid in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/num/dec2flt/mod.rs (Claimed by @camelid in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/array/iter.rs (Claimed by @camelid in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/ptr/non_null.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/hash/mod.rs (Claimed by @camelid in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/primitive_docs.rs (Claimed by @kofls in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/sys/wasi/ext/fs.rs (Claimed by @kofls in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/sys_common/os_str_bytes.rs (Claimed by @kofls in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/sys_common/poison.rs (Claimed by @kofls in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/convert/mod.rs (Claimed by @nixphix in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/iter/mod.rs (Claimed by @nixphix in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/slice/mod.rs (Claimed by @Amjad50 in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/clone.rs (Claimed by @denisvasilik in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/panic.rs (Claimed by @denisvasilik in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/iter/traits/iterator.rs (Claimed by @denisvasilik in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/marker.rs (Claimed by @camelid in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/net/ip.rs (Claimed by @jyn514 in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/fs.rs (Claimed by @jyn514 in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/ptr/mod.rs (Claimed by @camelid in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/sync/atomic.rs (Claimed by @denisvasilik in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/mem/mod.rs (Claimed by @camelid in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/iter/adapters/flatten.rs (Fixed by @pickfire in Simplify iter flatten struct doc #76707)
• library/core/src/iter/adapters/fuse.rs (Fixed by @pickfire in Simplify iter fuse struct doc #76778)
• library/alloc/src/collections/vec_deque.rs (Claimed by @denisvasilik in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/alloc/src/collections/vec_deque/drain.rs (Claimed by @denisvasilik in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/alloc/src/collections/btree/map.rs (Claimed by @denisvasilik in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/alloc/src/collections/linked_list.rs (Claimed by @denisvasilik in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/alloc/src/collections/binary_heap.rs (Claimed by @denisvasilik in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/sync/barrier.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/sync/once.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/iter/sources.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/iter/traits/collect.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/iter/traits/double_ended.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/iter/traits/exact_size.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/task/wake.rs (Claimed by @denisvasilik in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/std/src/collections/hash/map.rs (Claimed by @Amjad50 in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/ascii.rs (Claimed by @Amjad50 in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/option.rs (Claimed by @Amjad50 in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/str/mod.rs (Claimed by @Amjad50 in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/str/pattern.rs (Claimed by @Amjad50 in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/iter/adapters/mod.rs (Done by @pickfire in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/future/pending.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/future/poll_fn.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))
• library/core/src/future/ready.rs (Claimed by @poliorcetics in Tracking Issue for intra-doc links in libstd #75080 (comment))

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))

[denisvasilik]

Hi @jyn514, I would like to work on the following files:

• library/core/src/time.rs
• library/core/src/cmp.rs
• library/core/src/borrow.rs

[Manishearth]

Go for it!

[RDambrosio016]

Many of these links can be brute force replaced using a regex, for items such as ... ../../std/stuff/something.Item.html it can be brute forced with (\[.*\]: )\.\.\/\.\.\/std\/(\w*)\/(\w*)\.(\w*)\.html[^#], then replacing with $1std::$2::$4\n, many more like method ones can also be knocked out using regex replacement, that regex alone can knock out 384 links. So that might be something worth exploring so less work has to be done with replacing boring links like these

[RDambrosio016]

Method links and others (207) can be caught with (\[.*\]: )\.\.\/\.\.\/std\/(\w*)\/(\w*)\.(\w*)\.html#\w+\.(\w*) and replaced with $1std::$2::$4::$5\n, although as pointed out by @jyn514, some of these are broke even if the replacement is correct, so that will have to be checked manually.

[RDambrosio016]

Intrinsics furthermore has a lot (~80) of special ones which match (\[.*\])\(\.\.\/\.\.\/std\/(\w*)\/(\w*)\/\w*\.(\w*)\.\w+\) which can be replaced with $1(std::$2::$3::$4). There is another small use of this but with ../../std/module/stuff which can be matched with (\[.*\])\(\.\.\/\.\.\/std\/(\w*)\/\w*\.(\w*)\.\w+\) and replaced with $1(std::$2::$3)

[Manishearth]

Go ahead and try the regex approach, if there are conflcits we can try and resolve them.

[RDambrosio016]

I ran all replacements, then ran ./x.py test src/tools/linkchecker library/std, and there were no warnings. So i assume all of them worked correctly, however from my convo with @jyn514 some should not really work because they are fundamentally broken? so i am not quite sure if that is not the case or if testing is not working for me.

[Manishearth]

I'm not sure which ones you think will be broken.