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

[pitaj]

Helps with #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

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @jyn514 (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[jyn514]

Thanks for working on this :)

[jyn514]

Looks great! r=me when CI passes (feel free to ping me tomorrow if I forget to ping bors).

[pitaj]

I'm guessing errors like the following here are caused by not yet having #77267 (as seen in #77875):

error: unresolved link to `f32::sqrt`
    --> library/core/src/intrinsics.rs:1175:54
     |
1175 |     /// The stabilized version of this intrinsic is [`f32::sqrt`].
     |                                                      ^^^^^^^^^^^ the builtin type `f32` has no associated item named `sqrt`

I made that last commit which fixes those (not sure if it's the style you'd like to see, but it works).

I figured out that these errors here are because I was looking at the wrong TcpStream:

error: unresolved link to `self::net::TcpStream::read`
  --> library/std/src/io/buffered/bufreader.rs:24:26
   |
24 | /// [`TcpStream::read`]: crate::net::TcpStream::read
   |                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^ the struct `TcpStream` has no field or associated item named `read`
   |
   = note: `-D broken-intra-doc-links` implied by `-D warnings`

error: unresolved link to `self::net::TcpStream::write`
  --> library/std/src/io/buffered/bufwriter.rs:62:27
   |
62 | /// [`TcpStream::write`]: crate::net::TcpStream::write
   |                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the struct `TcpStream` has no field or associated item named `write`

error: unresolved link to `self::net::TcpStream::read`
  --> library/std/src/io/buffered/bufreader.rs:24:26
   |
24 | /// [`TcpStream::read`]: crate::net::TcpStream::read
   |                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^ the struct `TcpStream` has no field or associated item named `read`

I was looking at net_imp::TcpStream originally, but then I figured out that the TcpStream in tcp.rs is the real one. Except that one doesn't have its own read and write, instead it implements the traits:

• Read
  

  rust/library/std/src/net/tcp.rs

  Lines 550 to 553 in 9bd740a

  	impl Read for TcpStream {
  	fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
  	self.0.read(buf)
  	}

• Write
  

  rust/library/std/src/net/tcp.rs

  Lines 571 to 574 in 9bd740a

  	impl Write for TcpStream {
  	fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
  	self.0.write(buf)
  	}

So maybe those links should link to the trait methods as they already do? Because linking them like crate::net::TcpStream::write() doesn't work either:

error: unresolved link to `self::net::TcpStream::write`
  --> library/std/src/io/buffered/bufwriter.rs:62:27
   |
62 | /// [`TcpStream::write`]: crate::net::TcpStream::write()
   |                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the struct `TcpStream` has no function named `write`

[jyn514]

linking them like crate::net::TcpStream::write() doesn't work either

You probably need use crate::io::Write; trait items aren't resolved unless the trait is in scope.

I'm guessing errors like the following here are caused by not yet having #77267 (as seen in #77875)

Hmm, that seems like a separate bug - these aren't re-exports but just the primitives themselves. Did this happen with --stage 0 or --stage 1? (CI runs --stage 2, doc uses --stage 0 by default)

[pitaj]

trait items aren't resolved unless the trait is in scope.

Is there something special I have to do to import item for use with intra-doc links? Both look to be in scope to me:

• Write
  https://github.com/rust-lang/rust/blob/8ce7e5c88bc50ee39c574edf29c0ec5aabcec5af/library/std/src/io/buffered/bufwriter.rs#L2-L4
• Read
  https://github.com/rust-lang/rust/blob/8ce7e5c88bc50ee39c574edf29c0ec5aabcec5af/library/std/src/io/buffered/bufreader.rs#L3

Hmm, that seems like a separate bug - these aren't re-exports but just the primitives themselves. Did this happen with --stage 0 or --stage 1?

The "the builtin type f64 has no associated item named sqrt" errors occur for stage 0, stage 1, and stage 2.

These errors are all from CI. The "here" links link to CI logs. It looks to me like CI runs with --stage 0: https://github.com/rust-lang/rust/pull/78006/checks?check_run_id=1262780047#step:24:1769

[jyn514]

FYI I haven't forgotten about this but I don't have time to investigate all the bugs right now. I think the way forward is to file issues for the things that seem like they should work and revert the relevant changes for now.

[jyn514]

@pitaj I can't reproduce this failure locally.

$ cat tcp.rs
//! [`TcpStream::write`](std::net::TcpStream::write)
//! [`TcpStream::read`](std::net::TcpStream::read)
use std::io::{Read, Write};
$ rustdoc +rustc2 tcp.rs  # no output

Do you think you could try to make an example smaller than the full standard library?

Also, since this is only in the standard library, #54172 is definitely the wrong issue for this.

[pitaj]

@jyn514 I have been able to reproduce this in a crate by copying bufreader.rs and reexporting some things from std.

https://github.com/pitaj/rustdoc-78006-repro

I'll work tomorrow and see if I can prune it down some more.

[jyn514]

r=me with nit fixed

[jyn514]

@bors r+ rollup

[bors]

📌 Commit 8d48e3b has been approved by jyn514