Closed jyn514 closed 3 years ago
I'll continue with std::sync::*
I'll work on library/core/src/num/mod.rs
.
I'll work on
I'll also do:
I'll work on:
@jyn514 It looks like library/std/src/os/*/fs.rs
were already completed in #75395, so you can mark these as done:
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!
I don't think you can link to arrays, right?
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.
@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 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.
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
FYI slice/mod.rs
is 7k lines so you may want to claim that only after you've done the others.
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
I'll do library/core/src/ptr/non_null.rs
.
@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!
By the way, why is panic.md
a separate file and not inline docs?
I'll do library/core/src/slice/mod.rs
Is it ok to take this? Or anyone trying to do it now?
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.
Ok thanks
@jyn514 By the way, these have been merged, so you can mark them as complete:
I'll take library/std/src/net/ip.rs
and library/std/src/fs.rs
(not currently tracked)
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.
@jyn514 I think you probably want some backslashes before your dots to only match dots instead of matching anything, right?
For the .rs
and .html
you mean? In theory yes but in practice I didn't see any false positives.
@camelid I think library/core/src/mem/mod.rs is the last file that's not blocked :)
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.
I can take it @camelid if you don't have the time.
I opened the PR!
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).
@camelid does that take into account that you can't link from core
or alloc
to std
?
@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).
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 ../
.
Added to the tracking issue, thanks!
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
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.
Taking: library/core/src/iter/**
@poliorcetics I don't understand your comment - barrier.rs
and once.rs
are both in std, not core.
Ah no I'm mistaken on the files, sorry, I will find and note them.
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
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
library/core/src/mem/mod.rs
does not need any modifications, the suggested changes for the file here are there
@jyn514 You can remove these from the list, they no longer show up with the command on the latest master
commit:
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.
I covered stdarch https://github.com/rust-lang/stdarch/pull/914
@pickfire no worries, I'll just ignore them
In-progress
- [ ] library/core/src/num/mod.rs (Claimed by @jyn514 in https://github.com/rust-lang/rust/issues/75080#issuecomment-678635203)
What's the status of this?
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!
).
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.
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
.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.
Run
x.py doc library/std
. This shouldwarn(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 runrustfmt
.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
core
andstd
: https://github.com/rust-lang/rust/issues/75080#issuecomment-668985777Caveats
Primitives that have the same name as a module in scope must useThis was changed in https://github.com/rust-lang/rust/pull/75318,type@
to disambiguate them. For example, to link tochar
from std, usetype@char
.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!
core
tostd
(https://github.com/rust-lang/rust/issues/74481)--stage 0
, so you may not be able to make changes that require recently merged fixes: https://github.com/rust-lang/rust/pull/75368#issuecomment-672196852Associated items anywhere other than documenting the associated item itself (https://github.com/rust-lang/rust/pull/74489)FixedLinks on default function implementations for a trait (https://github.com/rust-lang/rust/issues/73829). Note that these will not warn if they fail to resolve, so you should be careful about modifying links on traits.FixedTODO 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
[i32::MAX]
(https://github.com/rust-lang/rust/pull/76093)[crate::ptr]
in libcore (https://github.com/rust-lang/rust/issues/76106)In-progress
Completed
Cannot be fixed
The following links cannot yet be fixed due to limitations in rustdoc.
[Vec::get_mut]
(https://github.com/rust-lang/rust/pull/75672#discussion_r472322546)