Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

convert slice doc link to intra-doc links #82950

Merged
merged 4 commits into from
Mar 12, 2021

Conversation

mockersf
Copy link
Contributor

@mockersf mockersf commented Mar 9, 2021

Continuing where #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 was available, but not sort_by_key even though it was linked in it's doc (same issue with as_ptr and as_mut_pbr). It becomes available if I implement DerefMut, as it needs an &mut self.

Code that will have dead links in its doc
pub struct A;
pub struct B;

impl std::ops::Deref for B{
    type Target = [A];

    fn deref(&self) -> &Self::Target {
        &A
    }
}

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

@rust-highfive
Copy link
Collaborator

r? @KodrAus

(rust-highfive has picked a reviewer for you, use r? to override)

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Mar 9, 2021
@jyn514
Copy link
Member

jyn514 commented Mar 10, 2021

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:

I would rather not do this. If you can't get the linkchecker to work, you can add an exception:

const LINKCHECK_EXCEPTIONS: &[(&str, &[&str])] = &[

@jyn514
Copy link
Member

jyn514 commented Mar 10, 2021

(the warning can't be ignored: error[E0710]: an unknown tool name found in scoped lint: rustdoc::broken_intra_doc_links )

You could use

#[cfg_attr(bootstrap, allow(broken_intra_doc_links)]
#[cfg_attr(not(bootstrap), allow(rustdoc::broken_intra_doc_links))]

But I'd rather you didn't, it means the links will be broken when looking at https://doc.rust-lang.org/nightly/core/primitive.slice.html#method.sort_by_key.

@jyn514 jyn514 added A-intra-doc-links Area: Intra-doc links, the ability to link to items in docs by name A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools labels Mar 10, 2021
@jyn514 jyn514 assigned jyn514 and unassigned KodrAus Mar 10, 2021
@jyn514 jyn514 added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Mar 10, 2021
library/core/src/slice/mod.rs Show resolved Hide resolved
library/core/src/slice/mod.rs Outdated Show resolved Hide resolved
@rust-log-analyzer

This comment has been minimized.

@jyn514 jyn514 added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Mar 10, 2021
@jyn514
Copy link
Member

jyn514 commented Mar 10, 2021

This looks great, thanks! Feel free to ping me when the tests pass and I'll approve the PR :)

@mockersf
Copy link
Contributor Author

@jyn514 tests are done!

@jyn514
Copy link
Member

jyn514 commented Mar 10, 2021

@bors r+ rollup

Thanks for the PR!

@bors
Copy link
Contributor

bors commented Mar 10, 2021

📌 Commit 232b9f1 has been approved by jyn514

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Mar 10, 2021
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...
bors added a commit to rust-lang-ci/rust that referenced this pull request Mar 12, 2021
Rollup of 11 pull requests

Successful merges:

 - rust-lang#80385 (Clarify what `Cell::replace` returns)
 - rust-lang#82571 (Rustdoc Json: Add tests for Reexports, and improve jsondocck)
 - rust-lang#82860 (Add `-Z unpretty` flag for the THIR)
 - rust-lang#82950 (convert slice doc link to intra-doc links)
 - rust-lang#82965 (Add spirv extension handling in compiletest)
 - rust-lang#82966 (update MSYS2 link in README)
 - rust-lang#82979 (Fix "run" button position in error index)
 - rust-lang#83001 (Ignore Vim swap files)
 - rust-lang#83003 (rustdoc: tweak the search index format)
 - rust-lang#83013 (Adjust some `#[cfg]`s to take non-Unix non-Windows operating systems into account)
 - rust-lang#83018 (Reintroduce accidentally deleted assertions.)

Failed merges:

r? `@ghost`
`@rustbot` modify labels: rollup
@bors bors merged commit 16ce4f7 into rust-lang:master Mar 12, 2021
@rustbot rustbot added this to the 1.52.0 milestone Mar 12, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools A-intra-doc-links Area: Intra-doc links, the ability to link to items in docs by name S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants