Convert primitives in the standard library to intra-doc links #80189
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
jyn514
added
A-docs
|
r? @shepmaster (rust-highfive has picked a reviewer for you, use r? to override) |
rust-highfive
added
the
S-waiting-on-review
jyn514
removed
the
S-waiting-on-review
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
jyn514
added
S-waiting-on-author
jyn514
force-pushed
the
convert-primitives
branch
2 times, most recently
from
37cfcfa to
4ddfbb7
Compare
This comment has been minimized.
This comment has been minimized.
Note that float methods in `core::intrinsics` weren't converted because they are only defined in `std` (using language item hacks).
jyn514
force-pushed
the
convert-primitives
branch
from
4ddfbb7 to
4d46735
Compare
jyn514
added
S-waiting-on-review
|
r? @poliorcetics |
|
✌️ @poliorcetics can now approve this pull request |
poliorcetics
approved these changes
Mar 2, 2021
| @@ -216,7 +216,7 @@ mod spec_extend; | |||
| /// # Slicing | |||
| /// | |||
| /// A `Vec` can be mutable. Slices, on the other hand, are read-only objects. | |||
| /// To get a [slice], use [`&`]. Example: | |||
| /// To get a [slice][prim@slice], use [`&`]. Example: | |||
There was a problem hiding this comment.
Just using '&' works for a link !? Intra doc links are even more amazing than I thought
There was a problem hiding this comment.
Yes, although some people wish it didn't 😆 #80181 (comment)
| /// [`is_null`]: ../std/primitive.pointer.html#method.is_null | ||
| /// [`offset`]: ../std/primitive.pointer.html#method.offset | ||
| /// [`is_null`]: pointer::is_null | ||
| /// [`offset`]: pointer::offset |
There was a problem hiding this comment.
This is not related to this PR specifically nor is it blocking, but should we recommend using things like () and ! more when possible ?
There are hundreds of links where a () could be added, maybe it's noise ?
There was a problem hiding this comment.
I definitely don't think we need to recommend () in the link address itself, it will never show up in the rendered documentation. I'm ambivalent about whether to show it in the link text; it doesn't hurt, but I don't know if it helps all that much.
|
@bors r+ rollup |
|
📌 Commit 4d46735 has been approved by |
bors
added
S-waiting-on-bors
bors
added a commit
to rust-lang-ci/rust
that referenced
this pull request
Mar 2, 2021
Rollup of 10 pull requests Successful merges: - rust-lang#80189 (Convert primitives in the standard library to intra-doc links) - rust-lang#80874 (Update intra-doc link documentation to match the implementation) - rust-lang#82376 (Add option to enable MIR inlining independently of mir-opt-level) - rust-lang#82516 (Add incomplete feature gate for inherent associate types.) - rust-lang#82579 (Fix turbofish recovery with multiple generic args) - rust-lang#82593 (Teach rustdoc how to display WASI.) - rust-lang#82597 (Get TyCtxt from self instead of passing as argument in AutoTraitFinder) - rust-lang#82627 (Erase late bound regions to avoid ICE) - rust-lang#82661 (:arrow_up: rust-analyzer) - rust-lang#82691 (Update books) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup
Dylan-DPC-zz
pushed a commit
to Dylan-DPC-zz/rust
that referenced
this pull request
Mar 11, 2021
…n514 convert slice doc link to intra-doc links Continuing where rust-lang#80189 stopped, with `core::slice`. I had an issue with two dead links in my doc when implementing `Deref<Target = [T]>` for one of my type. This means that [`binary_search_by_key`](https://doc.rust-lang.org/nightly/std/primitive.slice.html#method.binary_search_by_key) was available, but not [`sort_by_key`](https://doc.rust-lang.org/nightly/std/primitive.slice.html#method.sort_by_key) even though it was linked in it's doc (same issue with [`as_ptr`](https://doc.rust-lang.org/nightly/std/primitive.slice.html#method.as_ptr) and [`as_mut_pbr`](https://doc.rust-lang.org/nightly/std/primitive.slice.html#method.as_mut_ptr)). It becomes available if I implement `DerefMut`, as it needs an `&mut self`. <details> <summary>Code that will have dead links in its doc</summary> ```rust pub struct A; pub struct B; impl std::ops::Deref for B{ type Target = [A]; fn deref(&self) -> &Self::Target { &A } } ``` </details> I removed the link to `sort_by_key` from `binary_search_by_key` doc as I didn't find a nice way to have a live link: - `binary_search_by_key` is in `core` - `sort_by_key` is in `alloc` - intra-doc link `slice::sort_by_key` doesn't work, as `alloc` is not available when `core` is being build (the warning can't be ignored: ```error[E0710]: an unknown tool name found in scoped lint: `rustdoc::broken_intra_doc_links` ```) - keeping the link as an anchor `#method.sort_by_key` meant a dead link - an absolute link would work but doesn't feel right...
JohnTitor
added a commit
to JohnTitor/rust
that referenced
this pull request
Mar 11, 2021
…n514 convert slice doc link to intra-doc links Continuing where rust-lang#80189 stopped, with `core::slice`. I had an issue with two dead links in my doc when implementing `Deref<Target = [T]>` for one of my type. This means that [`binary_search_by_key`](https://doc.rust-lang.org/nightly/std/primitive.slice.html#method.binary_search_by_key) was available, but not [`sort_by_key`](https://doc.rust-lang.org/nightly/std/primitive.slice.html#method.sort_by_key) even though it was linked in it's doc (same issue with [`as_ptr`](https://doc.rust-lang.org/nightly/std/primitive.slice.html#method.as_ptr) and [`as_mut_pbr`](https://doc.rust-lang.org/nightly/std/primitive.slice.html#method.as_mut_ptr)). It becomes available if I implement `DerefMut`, as it needs an `&mut self`. <details> <summary>Code that will have dead links in its doc</summary> ```rust pub struct A; pub struct B; impl std::ops::Deref for B{ type Target = [A]; fn deref(&self) -> &Self::Target { &A } } ``` </details> I removed the link to `sort_by_key` from `binary_search_by_key` doc as I didn't find a nice way to have a live link: - `binary_search_by_key` is in `core` - `sort_by_key` is in `alloc` - intra-doc link `slice::sort_by_key` doesn't work, as `alloc` is not available when `core` is being build (the warning can't be ignored: ```error[E0710]: an unknown tool name found in scoped lint: `rustdoc::broken_intra_doc_links` ```) - keeping the link as an anchor `#method.sort_by_key` meant a dead link - an absolute link would work but doesn't feel right...
JohnTitor
added a commit
to JohnTitor/rust
that referenced
this pull request
Mar 11, 2021
…n514 convert slice doc link to intra-doc links Continuing where rust-lang#80189 stopped, with `core::slice`. I had an issue with two dead links in my doc when implementing `Deref<Target = [T]>` for one of my type. This means that [`binary_search_by_key`](https://doc.rust-lang.org/nightly/std/primitive.slice.html#method.binary_search_by_key) was available, but not [`sort_by_key`](https://doc.rust-lang.org/nightly/std/primitive.slice.html#method.sort_by_key) even though it was linked in it's doc (same issue with [`as_ptr`](https://doc.rust-lang.org/nightly/std/primitive.slice.html#method.as_ptr) and [`as_mut_pbr`](https://doc.rust-lang.org/nightly/std/primitive.slice.html#method.as_mut_ptr)). It becomes available if I implement `DerefMut`, as it needs an `&mut self`. <details> <summary>Code that will have dead links in its doc</summary> ```rust pub struct A; pub struct B; impl std::ops::Deref for B{ type Target = [A]; fn deref(&self) -> &Self::Target { &A } } ``` </details> I removed the link to `sort_by_key` from `binary_search_by_key` doc as I didn't find a nice way to have a live link: - `binary_search_by_key` is in `core` - `sort_by_key` is in `alloc` - intra-doc link `slice::sort_by_key` doesn't work, as `alloc` is not available when `core` is being build (the warning can't be ignored: ```error[E0710]: an unknown tool name found in scoped lint: `rustdoc::broken_intra_doc_links` ```) - keeping the link as an anchor `#method.sort_by_key` meant a dead link - an absolute link would work but doesn't feel right...
JohnTitor
added a commit
to JohnTitor/rust
that referenced
this pull request
Mar 11, 2021
…n514 convert slice doc link to intra-doc links Continuing where rust-lang#80189 stopped, with `core::slice`. I had an issue with two dead links in my doc when implementing `Deref<Target = [T]>` for one of my type. This means that [`binary_search_by_key`](https://doc.rust-lang.org/nightly/std/primitive.slice.html#method.binary_search_by_key) was available, but not [`sort_by_key`](https://doc.rust-lang.org/nightly/std/primitive.slice.html#method.sort_by_key) even though it was linked in it's doc (same issue with [`as_ptr`](https://doc.rust-lang.org/nightly/std/primitive.slice.html#method.as_ptr) and [`as_mut_pbr`](https://doc.rust-lang.org/nightly/std/primitive.slice.html#method.as_mut_ptr)). It becomes available if I implement `DerefMut`, as it needs an `&mut self`. <details> <summary>Code that will have dead links in its doc</summary> ```rust pub struct A; pub struct B; impl std::ops::Deref for B{ type Target = [A]; fn deref(&self) -> &Self::Target { &A } } ``` </details> I removed the link to `sort_by_key` from `binary_search_by_key` doc as I didn't find a nice way to have a live link: - `binary_search_by_key` is in `core` - `sort_by_key` is in `alloc` - intra-doc link `slice::sort_by_key` doesn't work, as `alloc` is not available when `core` is being build (the warning can't be ignored: ```error[E0710]: an unknown tool name found in scoped lint: `rustdoc::broken_intra_doc_links` ```) - keeping the link as an anchor `#method.sort_by_key` meant a dead link - an absolute link would work but doesn't feel right...
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Blocked on #80181. I forgot that this needs to wait for the beta bump so the standard library can be documented with
doc --stage 0.Notably I didn't convert
core::slicebecause it's like 50 links and I got scared 😨