-
Notifications
You must be signed in to change notification settings - Fork 12.8k
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
Use intra-doc links in str
and BTreeSet
#74453
Conversation
(rust_highfive has picked a reviewer for you, use r? to override) |
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.
This reminds me why I love intra-doc links! This looks great :) There are a lot of broken links though. I guess the link checker won't check those until #71670 lands, can we wait for that?
@@ -97,8 +95,7 @@ impl<T: fmt::Debug> fmt::Debug for Iter<'_, T> { | |||
/// This `struct` is created by the [`into_iter`] method on [`BTreeSet`] | |||
/// (provided by the `IntoIterator` trait). See its documentation for more. | |||
/// | |||
/// [`BTreeSet`]: struct.BTreeSet.html | |||
/// [`into_iter`]: struct.BTreeSet.html#method.into_iter | |||
/// [`into_iter`]: BTreeSet#method.into_iter |
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 think this should work:
/// [`into_iter`]: BTreeSet#method.into_iter | |
/// [`into_iter`]: BTreeSet::into_iter |
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.
Nah, it's a trait method
@@ -143,7 +142,7 @@ impl FromStr for bool { | |||
|
|||
/// An error returned when parsing a `bool` using [`from_str`] fails | |||
/// | |||
/// [`from_str`]: ../../std/primitive.bool.html#method.from_str | |||
/// [`from_str`]: FromStr::from_str |
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.
Do we support <bool as FromStr>::from_str
? If not that seems like a good addition, we could also overload <bool as FromStr>
to link to the trait implementation. No need to do anything for this PR though.
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.
We do not
@@ -266,8 +265,7 @@ impl Utf8Error { | |||
/// that it is valid UTF-8. `from_utf8()` checks to ensure that the bytes are valid | |||
/// UTF-8, and then does the conversion. | |||
/// | |||
/// [`&str`]: ../../std/primitive.str.html | |||
/// [`u8`]: ../../std/primitive.u8.html | |||
/// [`&str`]: str |
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.
Maybe we should strip references automatically? Not sure how that would play with slices eventually though.
/// into a string slice, use the [`str::from_utf8`] function. | ||
/// | ||
/// [`str::from_utf8`]: ./str/fn.from_utf8.html | ||
/// into a string slice, use the [`from_utf8`] function. |
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.
Let's keep the same link text.
/// into a string slice, use the [`from_utf8`] function. | |
/// into a string slice, use the [`str::from_utf8`](from_utf8) function. |
src/libcore/str/mod.rs
Outdated
@@ -2429,8 +2416,7 @@ impl str { | |||
/// The caller must ensure that the returned pointer is never written to. | |||
/// If you need to mutate the contents of the string slice, use [`as_mut_ptr`]. | |||
/// | |||
/// [`u8`]: primitive.u8.html | |||
/// [`as_mut_ptr`]: #method.as_mut_ptr | |||
/// [`as_mut_ptr`]: str::method.as_mut_ptr |
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.
/// [`as_mut_ptr`]: str::method.as_mut_ptr | |
/// [`as_mut_ptr`]: str::as_mut_ptr |
src/libcore/str/mod.rs
Outdated
@@ -2954,7 +2932,7 @@ impl str { | |||
/// | |||
/// To split by Unicode `Whitespace` instead, use [`split_whitespace`]. | |||
/// | |||
/// [`split_whitespace`]: #method.split_whitespace | |||
/// [`split_whitespace`]: str::method.split_whitespace |
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.
/// [`split_whitespace`]: str::method.split_whitespace | |
/// [`split_whitespace`]: str::split_whitespace |
@@ -3068,8 +3046,7 @@ impl str { | |||
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a | |||
/// function or closure that determines if a character matches. | |||
/// | |||
/// [`char`]: primitive.char.html | |||
/// [pattern]: str/pattern/index.html | |||
/// [pattern]: self::pattern |
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.
Hmm, this is not very clear that it's the module and not an associated function ... but I guess as long as the link works it's fine.
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.
It is, associated functions are Self
Hmm, well it caught at least some of them.
but I would still prefer to wait for #71670. |
dba5d18
to
699c9e0
Compare
Fixed the links. The dot made us treat it as a URL and skip the lint (which is expected). |
Oh huh, I forgot that @lzutao turned on
|
699c9e0
to
748634e
Compare
Fixed. We can't link to any libstd things from libcore, so I reverted those. |
r=me once CI is passing |
@bors r=jyn514 that's what bors is for 😄 (and when making rollups we typically make sure CI is passing) |
📌 Commit 748634e has been approved by |
This PR introduces quite a few regressions (as also noted in #74061) which I think would be unfortunate to add. In particular, many of the links are switched to remote links to https://doc.rust-lang.org/nightly/. Also, though not as severe, many of the primitive links now go to the module of the same name. |
@ehuss I don't consider it a regression for the links to link to doc.rlo. The primitive links can be fixed if we want. |
FWIW in my local build the links do not link to doc.rlo, they link locally. I think what you're seeing is #74458 |
Use intra-doc links in `str` and `BTreeSet` Fixes rust-lang#32129, fixes rust-lang#32130 A _slight_ degradation in quality is that the `#method.foo` links would previously link to the same page on `String`'s documentation, and now they will navigate to `str`. Not a big deal IMO, and we can also try to improve that.
Use intra-doc links in `str` and `BTreeSet` Fixes rust-lang#32129, fixes rust-lang#32130 A _slight_ degradation in quality is that the `#method.foo` links would previously link to the same page on `String`'s documentation, and now they will navigate to `str`. Not a big deal IMO, and we can also try to improve that.
Use intra-doc links in `str` and `BTreeSet` Fixes rust-lang#32129, fixes rust-lang#32130 A _slight_ degradation in quality is that the `#method.foo` links would previously link to the same page on `String`'s documentation, and now they will navigate to `str`. Not a big deal IMO, and we can also try to improve that.
Why not? A fair bit of effort goes into making sure the documentation is usable offline. I also find it confusing when browsing the stable docs, then ending up (without warning) in the nightly docs, using something that appears to be stable, only to learn much later that it is not stable (or doesn't exist at all on stable). To be clear, it is better to fix the broken links on the String page, but I consider it a backstep in other regards that should (eventually) be fixed.
An example is |
@ehuss That's only on the libcore docs, it's because libcore is weird, yes. We might be able to fix that, I'll file an issue. |
Shit, closed the PR by mistake |
Opened as #74453 |
@ehuss oh, right, this is because primitives only exist in |
That seems weird, shouldn't they be in libcore? |
…arth Rollup of 11 pull requests Successful merges: - rust-lang#72414 ( Add lazy initialization primitives to std) - rust-lang#74069 (Compare tagged/niche-filling layout and pick the best one) - rust-lang#74418 (ci: Set `shell: bash` as a default, remove duplicates) - rust-lang#74441 (bootstrap.py: patch RPATH on NixOS to handle the new zlib dependency.) - rust-lang#74444 (Add regression test for rust-lang#69414) - rust-lang#74448 (improper_ctypes_definitions: allow `Box`) - rust-lang#74449 (Test codegen of compare_exchange operations) - rust-lang#74450 (Fix `Safety` docs for `from_raw_parts_mut`) - rust-lang#74453 (Use intra-doc links in `str` and `BTreeSet`) - rust-lang#74457 (rustbuild: drop tool::should_install) - rust-lang#74464 (Use pathdiff crate) Failed merges: r? @ghost
Fixes #32129, fixes #32130
A slight degradation in quality is that the
#method.foo
links would previously link to the same page onString
's documentation, and now they will navigate tostr
. Not a big deal IMO, and we can also try to improve that.