rust-lang / rust

Empowering everyone to build reliable and efficient software.
https://www.rust-lang.org
Other
98.38k stars 12.72k forks source link

Tracking Issue for intra-doc links in libstd #75080

Closed jyn514 closed 3 years ago

jyn514 commented 4 years ago

This is a tracking issue for switching libstd to intra-doc links (rust-lang/rfcs#1946, https://github.com/rust-lang/rust/pull/74430#issuecomment-664693080).

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

    rewrite it as

    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 https://github.com/rust-lang/rust/pull/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

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 https://github.com/rust-lang/rust/pull/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!

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

In-progress

Completed

Cannot be fixed

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

LeSeulArtichaut commented 4 years ago

I'll continue with std::sync::*

jyn514 commented 4 years ago

I'll work on library/core/src/num/mod.rs.

LeSeulArtichaut commented 4 years ago

I'll work on

LeSeulArtichaut commented 4 years ago

I'll also do:

kofls commented 4 years ago

I'll work on:

camelid commented 4 years ago

@jyn514 It looks like library/std/src/os/*/fs.rs were already completed in #75395, so you can mark these as done:

camelid commented 4 years ago

I'll take (many of these are relatively small):

Also, can library/core/src/macros/panic.md really be switched over to intra-doc links since it's MarkDown?

UPDATE (9/16/2020): All done!

camelid commented 4 years ago

I don't think you can link to arrays, right?

jyn514 commented 4 years ago

I updated the fs.rs files.

Also, can library/core/src/macros/panic.md really be switched over to intra-doc links since it's MarkDown?

No, good catch. That one should be left as-is, I removed it from the tracking issue.

I don't think you can link to arrays, right?

Correct, see #63351.

camelid commented 4 years ago

@jyn514 It seems that MarkDown files were converted to use intra-doc links in #75530. Maybe we can switch to intra-doc in library/core/src/macros/panic.md?

jyn514 commented 4 years ago

@jyn514 It seems that MarkDown files were converted to use intra-doc links in #75530. Maybe we can switch to intra-doc in library/core/src/macros/panic.md?

Looking at those files it looks like they're documented with doc(include = file.md). So rustdoc doesn't seem them as markdown files, just part of the code: https://github.com/rust-lang/rust/blob/84539eb7b5de1b15467c591dcfb272fefa488bc8/library/std/src/os/raw/mod.rs#L11

If you can get rustdoc to create the links for markdown files, I think it's fine to convert them too, but I'd want to make sure the pass is actually being run and the links aren't silently being ignored.

nixphix commented 4 years ago

I'll work on the remaining mod.rs if they are not claimed

 library/core/src/convert/mod.rs
 library/core/src/iter/mod.rs
jyn514 commented 4 years ago

FYI slice/mod.rs is 7k lines so you may want to claim that only after you've done the others.

nixphix commented 4 years ago

FYI slice/mod.rs is 7k lines so you may want to claim that only after you've done the others.

sure, updated the claim

poliorcetics commented 4 years ago

I'll do library/core/src/ptr/non_null.rs.

camelid commented 4 years ago

@jyn514 Looks like library/core/src/macros/panic.md is being included, so I opened a PR (#75927) with that. I'll make sure it's checked by hand though!

https://github.com/rust-lang/rust/blob/bf4342114e357f2934d59e12e31e94532ddb2adf/library/core/src/macros/mod.rs#L1

camelid commented 4 years ago

By the way, why is panic.md a separate file and not inline docs?

Amjad50 commented 4 years ago

I'll do library/core/src/slice/mod.rs

Amjad50 commented 4 years ago

Is it ok to take this? Or anyone trying to do it now?

jyn514 commented 4 years ago

Feel free to take it, but be warned that it's 7k lines. So if you want to do only a partial fix that's perfectly fine.

Amjad50 commented 4 years ago

Ok thanks

camelid commented 4 years ago

@jyn514 By the way, these have been merged, so you can mark them as complete:

jyn514 commented 4 years ago

I'll take library/std/src/net/ip.rs and library/std/src/fs.rs (not currently tracked)

jyn514 commented 4 years ago

Updated regex, ignoring primitives that can't be linked to, documentation that's not code, and files that have already been claimed:

rg '\[.*\]: \.\./.*' library/ | rg -v '\.\./(book|reference|nomicon|(std/|)primitive.(fn|slice|pointer|never).html)' | rg -v 'core/src/(mem|num|ptr|str)/mod.rs|core/src/marker.rs'

If you're working on core you can also add | rg -v 'struct.(Box|String|Vec|VecDeque|HashMap|HashSet).html', which ignores structs in alloc that can't be linked to.

camelid commented 4 years ago

@jyn514 I think you probably want some backslashes before your dots to only match dots instead of matching anything, right?

jyn514 commented 4 years ago

For the .rs and .html you mean? In theory yes but in practice I didn't see any false positives.

jyn514 commented 4 years ago

@camelid I think library/core/src/mem/mod.rs is the last file that's not blocked :)

camelid commented 4 years ago

Okay, I'll see if I have time to split it up tomorrow. If I can't after tomorrow, someone else can do it if they want to.

poliorcetics commented 4 years ago

I can take it @camelid if you don't have the time.

camelid commented 4 years ago

I opened the PR!

camelid commented 4 years ago

I think there are actually a bunch more links to transition. List generated with:

grep '\[.*\]: (trait|struct|enum|fn)\..*\.html*' -r library | awk -F: '{print $1}' | uniq | sort | sed 's/^/- /'

EDIT (9/17/2020): Updated list with latest commit on master (f3c923a13a4).

EDIT (10/11/2020): Updated list with latest commit on master (06a079c43ef).

jyn514 commented 4 years ago

@camelid does that take into account that you can't link from core or alloc to std?

camelid commented 4 years ago

@jyn514 The command should only list files that are the trait.Iterator.html form, so the list should only include local items. Here's the full grep output:

library/alloc/src/collections/linked_list.rs:/// [`into_iter`]: struct.LinkedList.html#method.into_iter
library/alloc/src/collections/binary_heap.rs://! [`BinaryHeap`]: struct.BinaryHeap.html
library/alloc/src/collections/binary_heap.rs:/// [`peek_mut`]: struct.BinaryHeap.html#method.peek_mut
library/alloc/src/collections/binary_heap.rs:/// [`BinaryHeap`]: struct.BinaryHeap.html
library/alloc/src/collections/binary_heap.rs:/// [`iter`]: struct.BinaryHeap.html#method.iter
library/alloc/src/collections/binary_heap.rs:/// [`BinaryHeap`]: struct.BinaryHeap.html
library/alloc/src/collections/binary_heap.rs:/// [`into_iter`]: struct.BinaryHeap.html#method.into_iter
library/alloc/src/collections/binary_heap.rs:/// [`BinaryHeap`]: struct.BinaryHeap.html
library/alloc/src/collections/binary_heap.rs:/// [`drain`]: struct.BinaryHeap.html#method.drain
library/alloc/src/collections/binary_heap.rs:/// [`BinaryHeap`]: struct.BinaryHeap.html
library/alloc/src/collections/binary_heap.rs:/// [`drain_sorted`]: struct.BinaryHeap.html#method.drain_sorted
library/alloc/src/collections/binary_heap.rs:/// [`BinaryHeap`]: struct.BinaryHeap.html
library/alloc/src/collections/vec_deque/drain.rs:/// [`drain`]: struct.VecDeque.html#method.drain
library/alloc/src/collections/vec_deque/drain.rs:/// [`VecDeque`]: struct.VecDeque.html
library/alloc/src/collections/btree/map.rs:/// [`Entry`]: enum.Entry.html
library/alloc/src/collections/btree/map.rs:/// [`Entry`]: enum.Entry.html
library/alloc/src/collections/vec_deque.rs:/// [`iter`]: struct.VecDeque.html#method.iter
library/alloc/src/collections/vec_deque.rs:/// [`VecDeque`]: struct.VecDeque.html
library/alloc/src/collections/vec_deque.rs:/// [`iter_mut`]: struct.VecDeque.html#method.iter_mut
library/alloc/src/collections/vec_deque.rs:/// [`VecDeque`]: struct.VecDeque.html
library/alloc/src/collections/vec_deque.rs:/// [`into_iter`]: struct.VecDeque.html#method.into_iter
library/alloc/src/collections/vec_deque.rs:/// [`VecDeque`]: struct.VecDeque.html
library/core/src/ascii.rs://! [`escape_default`]: fn.escape_default.html
library/core/src/ascii.rs:/// [`escape_default`]: fn.escape_default.html
library/core/src/iter/traits/exact_size.rs:/// [`Iterator`]: trait.Iterator.html
library/core/src/iter/traits/exact_size.rs:/// [`size_hint`]: trait.Iterator.html#method.size_hint
library/core/src/iter/traits/exact_size.rs:    /// [trait-level]: trait.ExactSizeIterator.html
library/core/src/iter/traits/exact_size.rs:    /// [`size_hint`]: trait.Iterator.html#method.size_hint
library/core/src/iter/traits/double_ended.rs:/// [`Iterator`]: trait.Iterator.html
library/core/src/iter/traits/double_ended.rs:    /// [trait-level]: trait.DoubleEndedIterator.html
library/core/src/iter/traits/collect.rs:/// [`Iterator`]: trait.Iterator.html
library/core/src/iter/traits/collect.rs:/// [`collect`]: trait.Iterator.html#method.collect
library/core/src/iter/traits/collect.rs:/// [`IntoIterator`]: trait.IntoIterator.html
library/core/src/iter/traits/collect.rs:/// [`FromIterator`]: trait.FromIterator.html
library/core/src/iter/traits/collect.rs:    /// [trait-level]: trait.Extend.html
library/core/src/iter/adapters/flatten.rs:/// [`flatten`]: trait.Iterator.html#method.flatten
library/core/src/iter/adapters/flatten.rs:/// [`Iterator`]: trait.Iterator.html
library/core/src/iter/adapters/mod.rs:    /// [`next()`]: trait.Iterator.html#method.next
library/core/src/iter/adapters/mod.rs:/// [`rev`]: trait.Iterator.html#method.rev
library/core/src/iter/adapters/mod.rs:/// [`Iterator`]: trait.Iterator.html
library/core/src/iter/adapters/mod.rs:/// [`copied`]: trait.Iterator.html#method.copied
library/core/src/iter/adapters/mod.rs:/// [`Iterator`]: trait.Iterator.html
library/core/src/iter/adapters/mod.rs:/// [`cloned`]: trait.Iterator.html#method.cloned
library/core/src/iter/adapters/mod.rs:/// [`Iterator`]: trait.Iterator.html
library/core/src/iter/adapters/mod.rs:/// [`cycle`]: trait.Iterator.html#method.cycle
library/core/src/iter/adapters/mod.rs:/// [`Iterator`]: trait.Iterator.html
library/core/src/iter/adapters/mod.rs:/// [`step_by`]: trait.Iterator.html#method.step_by
library/core/src/iter/adapters/mod.rs:/// [`Iterator`]: trait.Iterator.html
library/core/src/iter/adapters/mod.rs:/// [`map`]: trait.Iterator.html#method.map
library/core/src/iter/adapters/mod.rs:/// [`Iterator`]: trait.Iterator.html
library/core/src/iter/adapters/mod.rs:/// [`DoubleEndedIterator`]: trait.DoubleEndedIterator.html
library/core/src/iter/adapters/mod.rs:/// [`filter`]: trait.Iterator.html#method.filter
library/core/src/iter/adapters/mod.rs:/// [`Iterator`]: trait.Iterator.html
library/core/src/iter/adapters/mod.rs:/// [`filter_map`]: trait.Iterator.html#method.filter_map
library/core/src/iter/adapters/mod.rs:/// [`Iterator`]: trait.Iterator.html
library/core/src/iter/adapters/mod.rs:/// [`enumerate`]: trait.Iterator.html#method.enumerate
library/core/src/iter/adapters/mod.rs:/// [`Iterator`]: trait.Iterator.html
library/core/src/iter/adapters/mod.rs:/// [`peekable`]: trait.Iterator.html#method.peekable
library/core/src/iter/adapters/mod.rs:/// [`Iterator`]: trait.Iterator.html
library/core/src/iter/adapters/mod.rs:    /// [`next`]: trait.Iterator.html#tymethod.next
library/core/src/iter/adapters/mod.rs:/// [`skip_while`]: trait.Iterator.html#method.skip_while
library/core/src/iter/adapters/mod.rs:/// [`Iterator`]: trait.Iterator.html
library/core/src/iter/adapters/mod.rs:/// [`take_while`]: trait.Iterator.html#method.take_while
library/core/src/iter/adapters/mod.rs:/// [`Iterator`]: trait.Iterator.html
library/core/src/iter/adapters/mod.rs:/// [`map_while`]: trait.Iterator.html#method.map_while
library/core/src/iter/adapters/mod.rs:/// [`Iterator`]: trait.Iterator.html
library/core/src/iter/adapters/mod.rs:/// [`skip`]: trait.Iterator.html#method.skip
library/core/src/iter/adapters/mod.rs:/// [`Iterator`]: trait.Iterator.html
library/core/src/iter/adapters/mod.rs:/// [`take`]: trait.Iterator.html#method.take
library/core/src/iter/adapters/mod.rs:/// [`Iterator`]: trait.Iterator.html
library/core/src/iter/adapters/mod.rs:/// [`scan`]: trait.Iterator.html#method.scan
library/core/src/iter/adapters/mod.rs:/// [`Iterator`]: trait.Iterator.html
library/core/src/iter/adapters/mod.rs:/// [`inspect`]: trait.Iterator.html#method.inspect
library/core/src/iter/adapters/mod.rs:/// [`Iterator`]: trait.Iterator.html
library/core/src/iter/sources.rs:/// [`repeat`]: fn.repeat.html
library/core/src/iter/sources.rs:/// [`take`]: trait.Iterator.html#method.take
library/core/src/iter/sources.rs:/// [`repeat_with`]: fn.repeat_with.html
library/core/src/iter/sources.rs:/// [`repeat_with`]: fn.repeat_with.html
library/core/src/iter/sources.rs:/// [`take`]: trait.Iterator.html#method.take
library/core/src/iter/sources.rs:/// [`repeat`]: fn.repeat.html
library/core/src/iter/sources.rs:/// [`empty`]: fn.empty.html
library/core/src/iter/sources.rs:/// [`once`]: fn.once.html
library/core/src/iter/sources.rs:/// [`chain`]: trait.Iterator.html#method.chain
library/core/src/iter/sources.rs:/// [`once_with`]: fn.once_with.html
library/core/src/iter/sources.rs:/// [`once`]: fn.once.html
library/core/src/iter/sources.rs:/// [`chain`]: trait.Iterator.html#method.chain
library/core/src/iter/sources.rs:/// [`FusedIterator`]: trait.FusedIterator.html
library/core/src/iter/sources.rs:/// [`Iterator::size_hint`]: trait.Iterator.html#method.size_hint
library/core/src/iter/sources.rs:/// [`iter::from_fn`]: fn.from_fn.html
library/core/src/iter/sources.rs:/// [`successors`]: fn.successors.html
library/core/src/option.rs:/// [`Option::into_iter`]: enum.Option.html#method.into_iter
library/core/src/task/wake.rs:/// [`Waker`]: struct.Waker.html
library/core/src/task/wake.rs:/// [`RawWaker`]: struct.RawWaker.html
library/core/src/task/wake.rs:    /// [`Waker`]: struct.Waker.html
library/core/src/task/wake.rs:    /// [`RawWaker`]: struct.RawWaker.html
library/core/src/task/wake.rs:    /// [`Waker`]: struct.Waker.html
library/core/src/task/wake.rs:    /// [`RawWaker`]: struct.RawWaker.html
library/core/src/task/wake.rs:    /// [`Waker`]: struct.Waker.html
library/core/src/task/wake.rs:    /// [`RawWaker`]: struct.RawWaker.html
library/core/src/task/wake.rs:    /// [`RawWaker`]: struct.RawWaker.html
library/core/src/task/wake.rs:    /// [`Waker`]: struct.Waker.html
library/core/src/task/wake.rs:    /// [`RawWaker`]: struct.RawWaker.html
library/core/src/task/wake.rs:/// [`RawWaker`]: struct.RawWaker.html
library/core/src/task/wake.rs:    /// [`RawWaker`]: struct.RawWaker.html
library/core/src/task/wake.rs:    /// [`RawWakerVTable`]: struct.RawWakerVTable.html
library/core/src/future/pending.rs:/// [`pending`]: fn.pending.html
library/core/src/future/poll_fn.rs:/// [`poll_fn`]: fn.poll_fn.html
library/core/src/future/ready.rs:/// [`ready`]: fn.ready.html
library/core/src/str/pattern.rs://! [pattern-impls]: trait.Pattern.html#implementors
library/core/src/str/mod.rs:/// [fromutf8u]: fn.from_utf8_unchecked.html
library/core/src/str/mod.rs:/// [error]: struct.Utf8Error.html
library/core/src/str/mod.rs:/// [error]: struct.Utf8Error.html
library/core/src/str/mod.rs:/// [fromutf8]: fn.from_utf8.html
library/std/src/sync/barrier.rs:/// [`wait`]: struct.Barrier.html#method.wait
library/std/src/sync/barrier.rs:/// [`Barrier`]: struct.Barrier.html
library/std/src/sync/barrier.rs:    /// [`BarrierWaitResult`]: struct.BarrierWaitResult.html
library/std/src/sync/barrier.rs:    /// [`is_leader`]: struct.BarrierWaitResult.html#method.is_leader
library/std/src/sync/barrier.rs:    /// [`wait`]: struct.Barrier.html#method.wait
library/std/src/sync/once.rs:/// [`Once::new`]: struct.Once.html#method.new
library/std/src/sync/once.rs:/// [`call_once_force`]: struct.Once.html#method.call_once_force
library/std/src/sync/once.rs:/// [`Once`]: struct.Once.html
library/std/src/sync/once.rs:/// [`Once`]: struct.Once.html
library/std/src/sync/once.rs:    /// [poison]: struct.Mutex.html#poisoning
library/std/src/sync/once.rs:    /// [`call_once`]: struct.Once.html#method.call_once
library/std/src/sync/once.rs:    /// [`OnceState`]: struct.OnceState.html
library/std/src/sync/once.rs:    /// [`call_once_force`]: struct.Once.html#method.call_once_force
library/std/src/sync/once.rs:    /// [`Once`]: struct.Once.html
library/std/src/sync/once.rs:    /// [`Once`]: struct.Once.html
library/std/src/collections/hash/map.rs:/// [`Entry`]: enum.Entry.html
library/std/src/collections/hash/map.rs:/// [`RawEntryBuilderMut`]: struct.RawEntryBuilderMut.html
library/std/src/collections/hash/map.rs:/// [`Entry`]: enum.Entry.html
library/std/src/collections/hash/map.rs:/// [`Entry`]: enum.Entry.html
library/stdarch/crates/core_arch/src/x86/sse42.rs:/// [`_mm_cmpestri`]: fn._mm_cmpestri.html
library/stdarch/crates/core_arch/src/x86/sse42.rs:/// [`_mm_cmpistri`]: fn._mm_cmpistri.html

EDIT (9/17/2020): Updated the grep output with latest commit on master (f3c923a13a4).

camelid commented 4 years ago

I think these did not show up because the command that you ran to generate the to-do list requires the link to start with ../.

jyn514 commented 4 years ago

Added to the tracking issue, thanks!

poliorcetics commented 4 years ago

Taking:

library/std/src/sync/barrier.rs
library/std/src/sync/once.rs
library/core/src/future/pending.rs
library/core/src/future/poll_fn.rs
library/core/src/future/ready.rs
poliorcetics commented 4 years ago
library/std/src/sync/barrier.rs
library/std/src/sync/once.rs

Those files now only contains links to std so they cannot be updated to use intra-doc links more than they already are.

poliorcetics commented 4 years ago

Taking: library/core/src/iter/**

jyn514 commented 4 years ago

@poliorcetics I don't understand your comment - barrier.rs and once.rs are both in std, not core.

poliorcetics commented 4 years ago

Ah no I'm mistaken on the files, sorry, I will find and note them.

Amjad50 commented 4 years ago

I'll work on

library/std/src/collections/hash/map.rs
library/core/src/str/pattern.rs
library/core/src/option.rs
library/core/src/str/mod.rs
library/core/src/mem/mod.rs
library/core/src/ascii.rs
denisvasilik commented 4 years ago

I'll work on

library/alloc/src/collections/binary_heap.rs
library/alloc/src/collections/btree/map.rs
library/alloc/src/collections/linked_list.rs
library/alloc/src/collections/vec_deque.rs
library/alloc/src/collections/vec_deque/drain.rs
library/core/src/task/wake.rs
Amjad50 commented 4 years ago

library/core/src/mem/mod.rs does not need any modifications, the suggested changes for the file here are there

camelid commented 4 years ago

@jyn514 You can remove these from the list, they no longer show up with the command on the latest master commit:

pickfire commented 4 years ago

Taking: library/core/src/iter/**

@poliorcetics I already did those under iter/adapters/*. Sorry, I didn't saw your claim and I didn't claim, I just do.

pickfire commented 4 years ago

I covered stdarch https://github.com/rust-lang/stdarch/pull/914

poliorcetics commented 4 years ago

@pickfire no worries, I'll just ignore them

camelid commented 4 years ago

In-progress

What's the status of this?

jyn514 commented 4 years ago

Blocked on https://github.com/rust-lang/rust/issues/75809 (well, it's not technically blocked but I don't want to mess with stringify!).

camelid commented 4 years ago

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.