Tracking Issue for intra-doc links in libstd #75080

jyn514 · 2020-08-03T01:47:38Z

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

[`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.

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.

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

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

The text was updated successfully, but these errors were encountered:

denisvasilik · 2020-08-03T06:02:27Z

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 · 2020-08-03T06:47:24Z

Go for it!

RDambrosio016 · 2020-08-04T04:36:00Z

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 · 2020-08-04T04:39:13Z

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 · 2020-08-04T05:03:11Z

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 · 2020-08-04T05:47:26Z

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

RDambrosio016 · 2020-08-04T05:56:46Z

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 · 2020-08-04T07:57:48Z

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

jyn514 · 2020-08-04T12:29:55Z

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

Associated items anywhere other than documenting the associated item itself (#74489)

jyn514 · 2020-08-04T12:31:40Z

so i am not quite sure if that is not the case or if testing is not working for me.

You can check by manually introducing a broken link and see if it's caught. If so, the tests are working :) I recommend --keep-stage 0 --keep-stage 1 for that so you don't have to rebuild the compiler (edit: after building the compiler for the first time - you can't keep a stage that hasn't been built!).

denisvasilik · 2020-08-04T15:29:38Z

Hi @RDambrosio016, could you do that for time.rs cmp.rs and borrow.rs as well? It's great to have a more automated variant.

RDambrosio016 · 2020-08-04T15:56:58Z

@denisvasilik not quite sure what you mean by do it for those files, as far as i can see all of the replacements in those files work. I identified another pattern of ../../std/module/index.html, which can be matched with \.\.\/\.\.\/std\/(\w*)\/index\.html and replaced with std::$1, as well as ../../std/primitive.primitive.html (not only primitive but also macro and others) which can be matched with \.\.\/\.\.\/std\/\w*\.(\w*)\.html and replaced with std::$1. i am not aware of any other major patterns, but if you are then please post it here and make a regex replacement, or just post it and i will do it when i have time 👍

denisvasilik · 2020-08-04T20:38:54Z

I had troubles with files located under library/core. I guess it has something to do with the caveats mentioned above, which states that intra-doc links from core to std are not possible.

RDambrosio016 · 2020-08-04T20:40:45Z

Yeah a fair amount of these replacement may be broken, but the goal of this is to overall reduce the amount of changes needed to be done.

denisvasilik · 2020-08-05T05:19:07Z

Here's another regex slightly modified to match core and std.
Example matches:

[`Add`]: ../../std/ops/trait.Add.html
[`GlobalAlloc`]: ../../core/alloc/trait.GlobalAlloc.html

Regex: (\[.*\]: )\.\.\/\.\.\/(core|std)\/(\w*)\/(\w*)\.(\w*)\.html[^#]
Replace: $1$2::$3::$5\n

denisvasilik · 2020-08-05T05:59:20Z

I saw that I cannot reference std in time.rs. For example I tried to do the following replacements:

 [`ops`]: ../../std/ops/index.html
 [`ops`]: std::ops (results in unresolved link)
 [`ops`]: core::ops (results in unresolved link)

If I add use create::ops it works, but I get a warning, because that import is just used for documentation. Is there another way to handle this or should I just leave these kind of links as is?

jyn514 · 2020-08-05T12:15:47Z

If I add use create::ops it works, but I get a warning, because that import is just used for documentation. Is there another way to handle this or should I just leave these kind of links as is?

Use crate::ops in the link instead:

 [`ops`]: crate::ops

Intra-doc links follow (almost) exactly the same rules as normal name resolution.

chansuke · 2020-08-06T05:59:35Z

Thank you for the detailed explanation. I would like to work on:

library/core/src/mem/manually_drop.rs
library/core/src/mem/maybe_uninit.rs

poliorcetics · 2020-08-07T21:11:12Z

I'll take library/std/src/path.rs.

poliorcetics · 2020-08-08T14:25:53Z

Hello !

I wrote a Python (3.6+, tested with 3.7 and 3.8) script to help with this issue, here is the gist.

By default it will not modify the files you pass it, only showing what it would do. You can find more informations about it in the documentation of the script.

Feel free to use it to speed up the work but be aware it is not perfect and you still review the whole file as well as any changes it makes. It may miss lines or modify some that shouldn't be modified. It is not aware of uses so some modification will make the docs fail to compile but on the whole it should be good enough to help with this tedious task. 😄

The script should preserve indentation perfectly if nothing else so you shouldn't have to rerun x.py fmt <file> 🤞.

I attached an example of the output produced by the script, please check yours is similar before applying its proposed changes:

@rustbot

…, r=jyn514 Move to intra-doc links in library/std/src/path.rs Helps with rust-lang#75080. @rustbot modify labels: T-doc, A-intra-doc-links, T-rustdoc Known issue: The following links are broken (they are inside trait impls, undocumented in this file, inheriting from the original doc): - [`Hasher`] - [`Self`] (referencing `../primitive.slice.html`) - [`Ordering`]

@rustbot

…jyn514 Finish moving to intra doc links for std::sync Helps with rust-lang#75080. @rustbot modify labels: T-doc A-intra-doc-links r? @jyn514

@rustbot

…=jyn514 Use intra-doc links in core/src/iter when possible Helps with rust-lang#75080. I also updated lots of links to use `fn()` instead of `fn` when possible. @rustbot modify labels: T-doc A-intra-doc-links r? @jyn514

@rustbot

…jyn514 Finish moving to intra doc links for std::sync Helps with rust-lang#75080. @rustbot modify labels: T-doc A-intra-doc-links r? @jyn514

@rustbot

…=jyn514 Use intra-doc links in core/src/iter when possible Helps with rust-lang#75080. I also updated lots of links to use `fn()` instead of `fn` when possible. @rustbot modify labels: T-doc A-intra-doc-links r? @jyn514

@rustbot

…jyn514 Finish moving to intra doc links for std::sync Helps with rust-lang#75080. @rustbot modify labels: T-doc A-intra-doc-links r? @jyn514

camelid · 2020-10-11T20:54:23Z

In-progress

library/core/src/num/mod.rs (Claimed by @jyn514 in Tracking Issue for intra-doc links in libstd #75080 (comment))

What's the status of this?

jyn514 · 2020-10-11T20:59:45Z

Blocked on #75809 (well, it's not technically blocked but I don't want to mess with stringify!).

camelid · 2020-10-12T18:49:21Z

Links that can't yet be fixed

The following can be fixed or updated to be more specific after the beta release on the 27th (and #74489 is merged):

These can be fixed now! August 27th is long past and #74489 was merged a long time ago as well.

poliorcetics · 2020-10-12T21:03:53Z

#75701 has been closed for inactivity, can we work on it now or is there another PR for it ?

jyn514 · 2020-10-12T21:52:06Z

Sure, if you want to work on it go ahead.

poliorcetics · 2020-10-12T22:26:55Z

Will do !

pitaj · 2020-10-15T05:24:55Z

Are any of the "Unclaimed" things here actually unclaimed?

I can't find anything with [flush]: Write::flush that still uses the old links. Same with [TcpStream::read]: Read::read and [i32::MAX]. [crate::ptr] looks fixed too?

jyn514 · 2020-10-15T12:47:20Z

@pitaj yes

TcpStream::read linking to Read::read is still present on master:

rust/library/std/src/io/buffered.rs

Line 35 in 246d327

/// [`TcpStream::read`]: Read::read
As is core::convert:

rust/library/core/src/hint.rs

Line 101 in 246d327

/// [`std::convert::identity`]: https://doc.rust-lang.org/core/convert/fn.identity.html
Write::flush should instead be BufWriter::flush:

rust/library/std/src/io/buffered.rs

Line 494 in 246d327

/// [`flush`]: Write::flush
[f32::xxx]:

rust/library/core/src/intrinsics.rs

Line 1174 in 246d327

/// [`std::f32::sqrt`](../../std/primitive.f32.html#method.sqrt)

It's a little misleading because I said what they should be in some cases, not what they are. But there are still links that need to be fixed.

pitaj · 2020-10-15T14:25:07Z

Ah I see! Thanks for clearing that up.

pitaj · 2020-10-16T04:53:11Z

I'll claim std::io::buffered and core::intrinsics

core::convert looks fixed in master
https://github.com/rust-lang/rust/blob/master/library/core/src/hint.rs#L110

Use Intra-doc links for std::io::buffered Helps with rust-lang#75080. I used the implicit link style for intrinsics, as that was what `minnumf32` and others already had. `@rustbot` modify labels: T-doc, A-intra-doc-links r? `@jyn514`

Use Intra-doc links for std::io::buffered Helps with rust-lang#75080. I used the implicit link style for intrinsics, as that was what `minnumf32` and others already had. ``@rustbot`` modify labels: T-doc, A-intra-doc-links r? ``@jyn514``

…jyn514 More intra doc links Helps with rust-lang#75080. I did a commit by group of file, I can squash if wanted. `@rustbot` modify labels: T-doc, A-intra-doc-links r? `@jyn514`

GroteGnoom · 2021-01-07T14:24:54Z

Could [std::convert::identity]: crate::convert::identity be removed from the unclaimed list?

also [TcpStream::read]:
#78006

@jyn514

poliorcetics · 2021-01-07T22:04:21Z

library/core/src/str/mod.rs has been done in #77875

Convert core/num/mod.rs to intra-doc links Helps with rust-lang#75080. This can't convert the associated constants `MAX` and `MIN` until rust-lang#74489 is merged. r? `@poliorcetics`

sjakobi · 2021-03-27T01:54:46Z

Unclaimed

[crate::ptr] in libcore (intra-doc links: crate::ptr on a re-export of core::slice is not resolved in alloc #76106)

I can't find any old-style links in in library/core/src/ptr. I'm probably misunderstanding the task description though.

(And is whatever remains to be done still E-easy?!)

jyn514 · 2021-03-27T03:51:43Z

I think there are few enough links left to convert it's not useful to have a tracking issue for them.

jyn514 mentioned this issue Aug 3, 2020

Stabilize intra-doc links #74430

Merged

jyn514 added A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools E-mentor Call for participation: This issue has a mentor. Use #t-compiler/help on Zulip for discussion. labels Aug 3, 2020

chansuke mentioned this issue Aug 6, 2020

Use intra-doc links in mem::manually_drop & mem::maybe_uninit #75214

Merged

poliorcetics mentioned this issue Aug 8, 2020

Move to intra-doc links in library/std/src/path.rs #75293

Merged

jyn514 mentioned this issue Oct 2, 2020

docs: use intra-RustDoc links rather than URLs tokio-rs/tracing#940

Closed

poliorcetics mentioned this issue Oct 12, 2020

More intra doc links #77875

Merged

pitaj mentioned this issue Oct 16, 2020

Use Intra-doc links for std::io::buffered #78006

Merged

jyn514 mentioned this issue Dec 1, 2020

Convert clippy_lints to intra-doc links rust-lang/rust-clippy#6412

Closed

jyn514 closed this as completed Mar 27, 2021

m-ou-se mentioned this issue Mar 27, 2021

Adjust documentation links for slice::make_ascii_*case #83577

Merged

Tracking Issue for intra-doc links in libstd #75080

Tracking Issue for intra-doc links in libstd #75080

Comments

jyn514 commented Aug 3, 2020 • edited by camelid Loading

About tracking issues

Mentoring instructions (or rather, suggested workflow)

Suggested tools

Caveats

TODO list

Unclaimed

In-progress

Completed

Cannot be fixed

denisvasilik commented Aug 3, 2020

Manishearth commented Aug 3, 2020

RDambrosio016 commented Aug 4, 2020

RDambrosio016 commented Aug 4, 2020 • edited Loading

RDambrosio016 commented Aug 4, 2020

Manishearth commented Aug 4, 2020

RDambrosio016 commented Aug 4, 2020

Manishearth commented Aug 4, 2020

jyn514 commented Aug 4, 2020

jyn514 commented Aug 4, 2020 • edited Loading

denisvasilik commented Aug 4, 2020

RDambrosio016 commented Aug 4, 2020 • edited Loading

denisvasilik commented Aug 4, 2020

RDambrosio016 commented Aug 4, 2020

denisvasilik commented Aug 5, 2020

denisvasilik commented Aug 5, 2020

jyn514 commented Aug 5, 2020 • edited Loading

chansuke commented Aug 6, 2020

poliorcetics commented Aug 7, 2020

poliorcetics commented Aug 8, 2020 • edited Loading

camelid commented Oct 11, 2020

In-progress

jyn514 commented Oct 11, 2020

camelid commented Oct 12, 2020

Links that can't yet be fixed

poliorcetics commented Oct 12, 2020

jyn514 commented Oct 12, 2020

poliorcetics commented Oct 12, 2020

pitaj commented Oct 15, 2020

jyn514 commented Oct 15, 2020

pitaj commented Oct 15, 2020

pitaj commented Oct 16, 2020

GroteGnoom commented Jan 7, 2021 • edited Loading

poliorcetics commented Jan 7, 2021

sjakobi commented Mar 27, 2021

Unclaimed

jyn514 commented Mar 27, 2021

jyn514 commented Aug 3, 2020 •

edited by camelid

Loading

RDambrosio016 commented Aug 4, 2020 •

edited

Loading

jyn514 commented Aug 4, 2020 •

edited

Loading

RDambrosio016 commented Aug 4, 2020 •

edited

Loading

jyn514 commented Aug 5, 2020 •

edited

Loading

poliorcetics commented Aug 8, 2020 •

edited

Loading

GroteGnoom commented Jan 7, 2021 •

edited

Loading