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 👍

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

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

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.