-
Notifications
You must be signed in to change notification settings - Fork 619
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
doc: remove crate:: prefix for links #1660
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
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. |
rustls/src/lib.rs
Outdated
@@ -63,10 +63,10 @@ | |||
//! support WebAssembly. | |||
//! For more information, see [the supported `ring` target platforms][ring-target-platforms]. | |||
//! | |||
//! By providing a custom instance of the [`crate::crypto::CryptoProvider`] struct, you | |||
//! By providing a custom instance of the crypto::CryptoProvider struct, you |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So I guess the syncing of crate root docs and README is a good reason to keep them there in the README, too?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't understand the question.
It's a little disappointing that |
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 |
Maybe we could be doing:
Instead of this? It's a bit more localised. |
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:
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 |
7aec86d
to
c36323d
Compare
7939906
to
9cade84
Compare
@ctz Do you want to give this another pass? |
Instead, use `#[cfg(doc)]` to conditionally import names that we want to use in the docs. This provides a user-friendlier link name.
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.