Migration to intra-doc links

[realaravinth]

When working on #1771, I was also checking feasibility for our migration to intra-doc links and I'd like to share my findings and ask for suggestions:

Motivation

At the time of writing this, intra-doc is a nightly only feature but the standard library folks are aggressively migrating to it. So it might land in stable soon.

Problem

Running cargo doc in nightly breaks existing documentation at multiple places(441), at least that's what cargo deadlinks is reporting. I manually checked files at random but I couldn't find any breakage though. tracing::span::Span was correctly linked, please read next section for context.

cargo-deadlinks report analysis:

• Broken links:

 ➜  actix-web git:(master) ✗ cat broken-links | sort -u
	Linked file at path client/struct.Span.html does not exist!
	Linked file at path dev/fn.fn_service.html does not exist!
	Linked file at path dev/struct.JsonConfig.html does not exist!
	Linked file at path futures_core::stream::Stream does not exist!
	Linked file at path h1/futures_sink::Sink does not exist!
	Linked file at path /home/aravinth/code/actix-web/target/doc/std/primitive.u8.html does not exist!
	Linked file at path /home/aravinth/code/actix-web/target/doc/struct.Span.html does not exist!
	Linked file at path http/struct@GetAll does not exist!
	Linked file at path http/struct.Span.html does not exist!
	Linked file at path middleware/struct.Span.html does not exist!
	Linked file at path struct.JsonConfig.html does not exist!
	Linked file at path struct.PayloadConfig.html does not exist!
	Linked file at path struct.Span.html does not exist!
	Linked file at path ws/futures_sink::Sink does not exist!

• Total number of broken links:

➜  actix-web git:(master) ✗ cat  broken-links | wc -l
441

• Most number of duplicates:

  actix-web git:(master) ✗ rg "Span" broken-links | wc -l
426

Span is from tracing::span::Span that we are using in impl Instrument for logging purposes(?)

Conclusion:

We should be fine making the switch to nightly temporarily. There's at least one place where we can benefit from intra-doc links and tracing::span::Span seems like something that the end user might never use(?).

So do we start migrating now or wait for it to land in stable?

[robjtede]

Yes, we should start using intra doc links for all new references. In fact, we've already started:

• https://github.com/actix/actix-web/blob/master/src/request_data.rs#L47
• https://docs.rs/actix-web/3.2.0/actix_web/web/struct.ReqData.html

[realaravinth]

Huh, I didn't notice! :D

In that case, we should make changes our upload-doc CI workflow as it's using stable. The same page on master API doc has broken links.

I'll submit a PR to this effect and begin migration.