chore: audit all doc links

[ipetkov]

Many of the doc links currently point to arbitrary URLs or don't actually link anywhere.

We should instead rely on rustdoc's resolution feature to link to the appropriate item, and block the CI on any errors/warnings there.

[carllerche]

@ipetkov that would be great. Historically, that option wasn't mature enough, but maybe that works now 👍

[ghost]

Would we like to replace all static links by some kind of script?
So the script could replace for example
struct.DelayQueue.html#method.insert
with
tokio::stream::StreamMap::insert
(or whatever the correct path look like).

Potentially helpful link here
https://github.com/rust-lang/rfcs/blob/master/text/1946-intra-rustdoc-links.md

[Darksonn]

Using ripgrep you can quickly find a lot of these:

rg '(struct|trait|enum|macro|fn|attr|type)\.[a-zA-Z0-9_]*\.html|#method.'

[ghost]

I've made some changes #2381

Next steps

1. fix broken links in these files
   target/doc/tokio/runtime/struct.Runtime.html, line 2, col 32
   target/doc/tokio/net/struct.UdpSocket.html, line 19, col 41
   target/doc/tokio/io/struct.Error.html, line 1, col 4928
   target/doc/tokio/io/struct.Error.html, line 1, col 4983
   target/doc/tokio/io/struct.Error.html, line 1, col 5040
   target/doc/tokio/io/struct.Error.html, line 201, col 1294
   target/doc/tokio/net/struct.TcpListener.html, line 76, col 32
   target/doc/tokio/time/struct.DelayQueue.html, line 28, col 1
   target/doc/tokio/io/index.html, line 159, col 234
   target/doc/tokio/task/struct.LocalSet.html, line 27, col 37
   target/doc/tokio/time/delay_queue/struct.DelayQueue.html, line 28, col 1
   target/doc/tokio/task/struct.LocalSet.html, line 131, col 21
   target/doc/tokio/task/struct.LocalSet.html, line 132, col 31
2. replace all left #methods reference. Would be helpful to resolve Resolve intra-doc-links on Self for method rust-lang/rust#70802 first and than fix it with a script
3. review what left

[ghost]

Next steps

1. fix broken links in these files

Broken links are fixed in #2400

However, some of the links from #1473 (comment) couldn't be fixed, here's the overview

1. links on https://docs.rs/tokio/0.2.18/tokio/io/struct.Error.html
   1. https://docs.rs/tokio/0.2.18/tokio/io/trait.Read.html
   2. https://docs.rs/tokio/0.2.18/tokio/io/trait.Write.html
   3. https://docs.rs/tokio/0.2.18/tokio/io/trait.Seek.html
   4. https://docs.rs/tokio/0.2.18/tokio/ffi/struct.NulError.html

Should be fixed in rustdoc: rust-lang/rust#65983 because they are re-exports

2. links on https://docs.rs/tokio/0.2.18/tokio/time/struct.DelayQueue.html#implementation
   1. https://docs.rs/tokio/0.2.18/tokio/struct.Timer.html

Docs should re rephrased, because according to

git log 27e5b41067d01c0c9fac230c5addb58034201a63`

• tokio::timer::Timer is renamed to Driver and made private.

So Timer is now Driver, but Driver shouldn't be used in public docs.

3. links on https://docs.rs/tokio/0.2.18/tokio/task/struct.LocalSet.html#notes
   1. https://docs.rs/tokio/0.2.18/tokio/blocking/fn.in_place.html

What is in-place blocking in the docs (see below or the link above).
Perhaps it should be replaced with https://docs.rs/tokio/0.2.18/tokio/task/fn.block_in_place.html if this makes sense (can't tell for my own) or the doc should be reworded.

Since this function internally calls Runtime::block_on, and drives futures in the local task set inside that call to block_on, the local futures may not use in-place blocking.

[Darksonn]

Hey @xliiv, thank you for doing this!

The in-place blocking link should indeed be a link to block_in_place, as you suggested.

[ghost]

The in-place blocking link should indeed be a link to block_in_place, as you suggested.

Thanks, updated #2400 with 3f46ba7

[ghost]

2. links on docs.rs/tokio/0.2.18/tokio/time/struct.DelayQueue.html#implementation

   1. https://docs.rs/tokio/0.2.18/tokio/struct.Timer.html

Fixed in e19a0d4 commit and discussed in the thread starting with this comment #2400 (comment)

[Darksonn]

Links to AsyncRead/AsyncWrite on https://docs.rs/tokio-util/0.3.1/tokio_util/codec/length_delimited/index.html are broken.

[ghost]

Links to AsyncRead/AsyncWrite on docs.rs/tokio-util/0.3.1/tokio_util/codec/length_delimited/index.html are broken.

Thanks, I'll fix it as 3rd step of #1473 (comment) if it's not handled earlier

[Darksonn]

Note that #2423 was just opened.

[Darksonn]

Is there more work to do on this issue?

[ghost]

In short yes.

I would still change all #method.<name>. This can be done two ways

> rg '(struct|trait|enum|macro|fn|attr|type)\.[a-zA-Z0-9_]*\.html|#method.' -t rust -g '!target' -g '!tokio-test'|rg '#method'|wc -l
48

1. manually
2. by a script (the script way is easy if this issue is resolved Resolve intra-doc-links on Self for method rust-lang/rust#70802)

My plan is to finish resolved rust-lang/rust#70802 issue and get back to this issue.
If resolving 70802 issue takes longer i will fallback to point 1.
Ok?

[Darksonn]

Sounds good! No rush, I was just going through issues to figure out the status.

[ghost]

I need more time because, .. you know life. ;)

[ghost]

Status update..

In Short

With this MR #2575
we're fixing all easily fixable links and IMO we're good enough to close this issue.

In Long

Other non intra-links still exist. This is the complete list

1. http links

   1. missing dependency

   > rg '(struct|trait|enum|macro|fn|attr|type)\.[a-zA-Z0-9_]*\.html|#method.' -t rust -g '!target' -g '!tokio-test'|rg http
   tokio-util/src/codec/framed.rs:    /// [`split`]: https://docs.rs/futures/0.3/futures/stream/trait.StreamExt.html#method.split
   tokio-util/src/codec/framed.rs:    /// [`split`]: https://docs.rs/futures/0.3/futures/stream/trait.StreamExt.html#method.split
   tokio-util/src/codec/framed.rs:    /// [`split`]: https://docs.rs/futures/0.3/futures/stream/trait.StreamExt.html#method.split

   Here, we miss future dependency in tokio/cargo.toml. It's in dependency-dev section to be exact. When I moved future to dependency section, i was able to make the intra-links work. Though, adding future to deps, because of docs is not a solution :).

   2. recurrsion dependency

   tokio/src/time/delay_queue.rs:/// [`Stream`]: https://docs.rs/futures/0.1/futures/stream/trait.Stream.html
   tokio/src/io/mod.rs://! [`Encoder`]: https://docs.rs/tokio-util/0.3/tokio_util/codec/trait.Encoder.html
   tokio/src/io/mod.rs://! [`Decoder`]: https://docs.rs/tokio-util/0.3/tokio_util/codec/trait.Decoder.html
   tokio/src/io/mod.rs://! [`Sink`]: https://docs.rs/futures/0.3/futures/sink/trait.Sink.html
   tokio/src/fs/mod.rs://! [`AsyncRead`]: https://docs.rs/tokio-io/0.1/tokio_io/trait.AsyncRead.html

   Similar to one above, here we miss tokio_util depedency in cargo.toml.
   However, we can't add tokio_util to tokio deps., because tokio_util depends on tokio so it would be cyclic dependency.
   Perhaps we should keep regular links here as they are.

2. non-http links

tokio/src/lib.rs://! [main]: attr.main.html
tokio/src/runtime/mod.rs://! [`tokio::main`]: ../attr.main.html
tokio/src/runtime/mod.rs:    /// [main]: ../attr.main.html

This doesn't work. My guess, it's because of this? Maybe?

tokio/tokio/src/lib.rs

Lines 397 to 430 in a5c1a7d

	cfg_macros! {
	/// Implementation detail of the `select!` macro. This macro is **not**
	/// intended to be used as part of the public API and is permitted to
	/// change.
	#[doc(hidden)]
	pub use tokio_macros::select_priv_declare_output_enum;
	doc_rt_core! {
	cfg_rt_threaded! {
	// This is the docs.rs case (with all features) so make sure macros
	// is included in doc(cfg).
	#[cfg(not(test))] // Work around for rust-lang/rust#62127
	#[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
	pub use tokio_macros::main_threaded as main;
	#[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
	pub use tokio_macros::test_threaded as test;
	}
	cfg_not_rt_threaded! {
	#[cfg(not(test))] // Work around for rust-lang/rust#62127
	pub use tokio_macros::main_basic as main;
	pub use tokio_macros::test_basic as test;
	}
	}
	// Maintains old behavior
	cfg_not_rt_core! {
	#[cfg(not(test))]
	pub use tokio_macros::main;
	pub use tokio_macros::test;
	}
	}

For sure, I just checked intra-links for proc macros and it works, ..

Test details

extern crate proc_macro;
use proc_macro::TokenStream;

/// [`this_proc_macro`](crate::this_proc_macro)
#[proc_macro_attribute]
pub fn this_proc_macro(_attr: TokenStream, item: TokenStream) -> TokenStream { }

so .. If anyone wants to dig it, go ahead.

[ghost]

@Darksonn should we close it?
IMO, yes see #1473 (comment)