Use intra-doc links in `str` and `BTreeSet` by Manishearth · Pull Request #74453 · rust-lang/rust

Manishearth · 2020-07-17T19:52:38Z

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.

rust-highfive · 2020-07-17T19:52:42Z

r? @LukasKalbertodt

(rust_highfive has picked a reviewer for you, use r? to override)

jyn514

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?

jyn514 · 2020-07-17T20:11:50Z

I think this should work:
Suggested change
/// [`into_iter`]: BTreeSet#method.into_iter
/// [`into_iter`]: BTreeSet::into_iter

Nah, it's a trait method

jyn514 · 2020-07-17T20:13:58Z

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.

jyn514 · 2020-07-17T20:15:50Z

Maybe we should strip references automatically? Not sure how that would play with slices eventually though.

jyn514 · 2020-07-17T20:17:16Z

Let's keep the same link text.
Suggested change
/// into a string slice, use the [`from_utf8`] function.
/// into a string slice, use the [`str::from_utf8`](from_utf8) function.

jyn514 · 2020-07-17T20:17:46Z

Suggested change
/// [`as_mut_ptr`]: str::method.as_mut_ptr
/// [`as_mut_ptr`]: str::as_mut_ptr

jyn514 · 2020-07-17T20:18:10Z

Suggested change
/// [`split_whitespace`]: str::method.split_whitespace
/// [`split_whitespace`]: str::split_whitespace

jyn514 · 2020-07-17T20:18:28Z

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.

It is, associated functions are Self

jyn514 · 2020-07-17T20:23:59Z

Hmm, well it caught at least some of them.

 std/primitive.str.html:128: broken link - std/str::method.as_mut_ptr
std/primitive.str.html:434: broken link - std/str::method.split_whitespace
std/primitive.str.html:1212: broken link - std/str::method.to_ascii_lowercase
thread 'main' panicked at 'found some broken links', src/tools/linkchecker/main.rs:41:9

but I would still prefer to wait for #71670.

Manishearth · 2020-07-17T21:06:50Z

Fixed the links. The dot made us treat it as a URL and skip the lint (which is expected).

jyn514 · 2020-07-17T21:13:58Z

Oh huh, I forgot that @lzutao turned on deny(resolution_failure) (thank you ❤️). So we should be good merge once you fix the broken links.

 error: `[str::to_ascii_lowercase]` cannot be resolved, ignoring it.
--> src/libcore/str/mod.rs:4346:33
|
4346 | /// [`to_ascii_lowercase`]: str::to_ascii_lowercase
| ^^^^^^^^^^^^^^^^^^^^^^^ cannot be resolved, ignoring
|
note: the lint level is defined here
--> src/libcore/lib.rs:64:9
|
64 | #![deny(intra_doc_link_resolution_failure)] // rustdoc is run without -D warnings
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
= help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`
error: aborting due to previous error

Manishearth · 2020-07-17T21:15:40Z

Fixed. We can't link to any libstd things from libcore, so I reverted those.

jyn514 · 2020-07-17T21:17:10Z

r=me once CI is passing

Manishearth · 2020-07-17T21:18:23Z

@bors r=jyn514

that's what bors is for 😄 (and when making rollups we typically make sure CI is passing)

bors · 2020-07-17T21:18:24Z

📌 Commit 748634e has been approved by jyn514

ehuss · 2020-07-18T00:20:54Z

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.

Manishearth · 2020-07-18T00:28:10Z

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

Manishearth · 2020-07-18T00:30:51Z

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` Fixesrust-lang#32129, fixesrust-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.

ehuss · 2020-07-18T01:18:08Z

I don't consider it a regression for the links to link to doc.rlo.

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.

FWIW in my local build the links do not link to doc.rlo, they link locally. I think what you're seeing is #74458

An example is core/str/index.html. Almost all of the links in the descriptions there now go to the remote site. I'm guessing that core and alloc are unable to link to the primitive types? Perhaps that will need to be special cased?

Manishearth · 2020-07-18T01:40:19Z

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

Manishearth · 2020-07-18T01:43:22Z

Shit, closed the PR by mistake

Manishearth · 2020-07-18T01:45:14Z

Opened as #74453

Manishearth · 2020-07-18T01:49:07Z

@ehuss oh, right, this is because primitives only exist in std, and when documenting core we don't have std yet.

jyn514 · 2020-07-18T02:27:33Z

primitives only exist in std

That seems weird, shouldn't they be in libcore?

@ghost

…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

Manishearth requested a review from jyn514 July 17, 2020 19:52

rust-highfive assigned LukasKalbertodt Jul 17, 2020

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jul 17, 2020

Manishearth mentioned this pull request Jul 17, 2020
Stabilize intra-doc links #74430
Merged

jyn514 reviewed Jul 17, 2020
View reviewed changes

jyn514 mentioned this pull request Jul 17, 2020
rustdoc: Intra doc links from Deref/etc do not link to the same page #74458
Open

Use intra-doc links in BTreeSet docs
91314e2

Manishearth force-pushed the intra-doc-std branch from dba5d18 to 699c9e0Compare July 17, 2020 21:01

Use intra doc links in std::str
748634e

Manishearth force-pushed the intra-doc-std branch from 699c9e0 to 748634eCompare July 17, 2020 21:15

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 17, 2020

Manishearth mentioned this pull request Jul 18, 2020
Rollup of 12 pull requests #74466
Closed

Manishearth mentioned this pull request Jul 18, 2020
Rollup of 11 pull requests #74467
Closed

Manishearth mentioned this pull request Jul 18, 2020
Rollup of 11 pull requests #74468
Merged

Manishearth closed this Jul 18, 2020

Manishearth deleted the intra-doc-std branch July 18, 2020 01:14

Manishearth restored the intra-doc-std branch July 18, 2020 01:43

Manishearth mentioned this pull request Jul 18, 2020
Use intra-doc links in str and BTreeSet#74470
Merged

	/// [`into_iter`]: BTreeSet#method.into_iter
	/// [`into_iter`]: BTreeSet::into_iter

	/// into a string slice, use the [`from_utf8`] function.
	/// into a string slice, use the [`str::from_utf8`](from_utf8) function.

	/// [`as_mut_ptr`]: str::method.as_mut_ptr
	/// [`as_mut_ptr`]: str::as_mut_ptr

	/// [`split_whitespace`]: str::method.split_whitespace
	/// [`split_whitespace`]: str::split_whitespace

Uh oh!

Uh oh!

Conversation

Manishearth commented Jul 17, 2020

Uh oh!

rust-highfive commented Jul 17, 2020

Uh oh!

jyn514 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jyn514 commented Jul 17, 2020

Uh oh!

Manishearth commented Jul 17, 2020

Uh oh!

jyn514 commented Jul 17, 2020

Uh oh!

Manishearth commented Jul 17, 2020

Uh oh!

jyn514 commented Jul 17, 2020

Uh oh!

Manishearth commented Jul 17, 2020

Uh oh!

bors commented Jul 17, 2020

Uh oh!

ehuss commented Jul 18, 2020

Uh oh!

Manishearth commented Jul 18, 2020

Uh oh!

Manishearth commented Jul 18, 2020

Uh oh!

ehuss commented Jul 18, 2020

Uh oh!

Manishearth commented Jul 18, 2020

Uh oh!

Manishearth commented Jul 18, 2020

Uh oh!

Manishearth commented Jul 18, 2020

Uh oh!

Manishearth commented Jul 18, 2020

Uh oh!

jyn514 commented Jul 18, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants