doc: remove crate:: prefix for links

[jsha]

Instead, use #[cfg(doc)] to conditionally import names that we want to use in the docs. This provides a user-friendlier link name.

Also, remove rustdoc-style links from the section of src/lib.rs that gets extracted for the README, since they wind up as broken links in the README.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (74321cf) 95.90% compared to head (4915b59) 95.90%.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1660   +/-   ##
=======================================
  Coverage   95.90%   95.90%           
=======================================
  Files          78       78           
  Lines       16083    16083           
=======================================
  Hits        15424    15424           
  Misses        659      659           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[djc]

So I guess the syncing of crate root docs and README is a good reason to keep them there in the README, too?

[jsha]

I don't understand the question.

[ctz]

It's a little disappointing that [crate::Something] doesn't produce reasonable output -- maybe I'm wrong, but I'd expect the crate:: path to be dropped, as it doesn't make sense in the context of hyperlinked documentation.

[jsha]

Yeah, or even better, everything at the top level of the crate should be in-scope from the rustdoc perspective. That way you wouldn't have to type crate:: at all.

[ctz]

Maybe we could be doing:

diff --git a/rustls/src/builder.rs b/rustls/src/builder.rs
index 26de3adb..63f5a587 100644
--- a/rustls/src/builder.rs
+++ b/rustls/src/builder.rs
@@ -19,7 +19,7 @@ use std::sync::Arc;
 /// For settings besides these, see the fields of [`ServerConfig`] and [`ClientConfig`].
 ///
 /// The usual choice for protocol primitives is to call
-/// [`crate::ClientConfig::builder`]/[`ServerConfig::builder`]
+/// [`ClientConfig::builder`](crate::ClientConfig::builder)/[`ServerConfig::builder`]
 /// which will use rustls' default cryptographic provider and safe defaults for ciphersuites and
 /// supported protocol versions.
 ///

Instead of this? It's a bit more localised.

[jsha]

[`ClientConfig::builder`](crate::ClientConfig::builder)

This works, and we've done in in one place (which I haven't update in this PR, yet). But it gets verbose, runs into line length issues, and makes the un-rendered docs hard to read.

There's another approach:

[`ClientConfig::builder`]

...

[`ClientConfig::builder`]: crate::ClientConfig::builder

This is more concise but you wind up having to repeat it for every doc section that mentions that item. And I've found the extra typing is pretty tedious.

One additional benefit of use statements is that they can take advantage of IDE autocomplete, while comments cannot. So typing out long item names twice in comments is riskier. Also there's the potential for undetected typos (in the link text, not the link target).

[cpu]

@ctz Do you want to give this another pass?