More intra-doc links, add explicit exception list to linkchecker#74485

Manishearth · 2020-07-18T20:39:29Z

Fixes the broken links behind #32553

Progress on #32130 and #32129 except for a small number of links. Instead of whitelisting entire files, I've changed the code to whitelist specific links in specific files, and added a comment requesting people explain the reasons they add exceptions. I'm not sure if we should close those issues in favor of the already filed intra-doc link issues.

rust-highfive · 2020-07-18T20:39:32Z

r? @LukasKalbertodt

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

ollie27 · 2020-07-18T21:39:30Z

Fixes #32553

This won't actually fix #32553 because it is about the missing Methods from Deref<Target=str> section on the alloc::string::String page. This may be able to fix the broken links that were caused by that though.

Manishearth · 2020-07-18T21:56:32Z

@ollie27 oh heh I just copied the issue number from the source when I deleted the linkcheck line

jyn514

Thanks for working on this!

jyn514 · 2020-07-19T04:22:25Z

src/liballoc/string.rs

 ///
 /// You can create a `String` from a literal string with [`String::from`]:
 ///
+/// [`String::from`]: From::from


Let's link to the relevant impl, not just the trait (this is &'_ str)

Suggested change

/// [`String::from`]: From::from

/// [`String::from`]: #impl-From<%26%27_%20str>

the exact impl doesn't have special docs and the point is to reduce the direct links :)

I think linking to the type is helpful though. It's not clear that 'literal string' means &'_ str, especially to beginners.

Also, same comment as below about fragments loading faster than different pages.

We can just fix that with an &str link :)

src/liballoc/string.rs

jyn514 · 2020-07-19T04:27:57Z

src/libstd/collections/hash/map.rs

-/// [`with_capacity_and_hasher`]: #method.with_capacity_and_hasher
+/// [`RefCell`]: crate::cell::RefCell
+/// [`Cell`]: crate::cell::Cell
+/// [`default`]: Default::default


This now goes to the trait page, instead of the list of implementations. I know HashMap::default doesn't currently work, can we keep #method.default until then? We don't have the ambiguity of String::from because there can only be one Default impl.

IMO the trait page is fine but I'd rather get rid of the #s and have links work over having them link to the trait impl instead of the trait. I don't see a difference in utility there

The difference is that going to the trait takes you to a new page and away from the docs you were originally reading. #method.default loads basically instantaneously.

src/libstd/io/mod.rs

jyn514 · 2020-07-19T04:37:50Z

src/tools/linkchecker/main.rs

+const LINKCHECK_EXCEPTIONS: &[(&str, &[&str])] = &[
+    // These are methods on slice, and `Self` does not work on primitive impls
+    // in intra-doc links (intra-doc links are weird)
+    // https://github.com/rust-lang/rust/issues/62834 is necessary to be


I think you meant the issue on primitive types.

Suggested change

// https://github.com/rust-lang/rust/issues/62834 is necessary to be

// https://github.com/rust-lang/rust/issues/63351 is necessary to be

oh, in my mind the generic issue is also what blocks slice, but your thing works

jyn514 · 2020-07-19T04:37:56Z

src/tools/linkchecker/main.rs

+// are cases where that does not work
+const LINKCHECK_EXCEPTIONS: &[(&str, &[&str])] = &[
+    // These are methods on slice, and `Self` does not work on primitive impls
+    // in intra-doc links (intra-doc links are weird)


I actually meant to say "primitive impls are weird" lol

src/tools/linkchecker/main.rs

Co-authored-by: Joshua Nelson <joshua@yottadb.com>

jyn514 · 2020-07-19T05:45:52Z

@bors r+ rollup=iffy

The changes to linkchecker will mean any PR with broken links would break during rollup but not in a check build.

bors · 2020-07-19T05:45:53Z

📌 Commit ec966ae has been approved by jyn514

@ghost

…arth Rollup of 4 pull requests Successful merges: - rust-lang#74333 (Deny unsafe operations in unsafe functions in libstd/alloc.rs) - rust-lang#74356 (Remove combine function) - rust-lang#74419 (Add a thumbv4t-none-eabi target) - rust-lang#74485 (More intra-doc links, add explicit exception list to linkchecker) Failed merges: - rust-lang#74486 (Improve Read::read_exact documentation) r? @ghost

Manishearth added 4 commits July 18, 2020 09:43

More links in std::str

a594603

Use intra-doc links in alloc::String

d6d48b4

Use more intra-doc links in BTreeSet

3168b7d

Use intra-doc links in BTreeMap

4c48ac3

Manishearth requested a review from jyn514 July 18, 2020 20:39

rust-highfive assigned LukasKalbertodt Jul 18, 2020

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

Manishearth added 4 commits July 18, 2020 16:13

Use intra-doc links in std::io

26ba0e1

Use intra-doc links on HashMap

e53fea7

Use intra-doc links on HashSet

9392a5e

Add explicit exception list to linkchecker

a968093

Manishearth force-pushed the more-intra-doc branch from 7ee0f2a to a968093 Compare July 18, 2020 23:13

jyn514 added the A-intra-doc-links Area: Intra-doc links, the ability to link to items in docs by name label Jul 19, 2020

jyn514 reviewed Jul 19, 2020

View reviewed changes

tesuji mentioned this pull request Jul 19, 2020

Use intra-doc-link to fix broken links #74061

Closed

Manishearth and others added 4 commits July 18, 2020 22:30

Update src/tools/linkchecker/main.rs

4a324b8

Co-authored-by: Joshua Nelson <joshua@yottadb.com>

Update src/libstd/io/mod.rs

8d470b5

Co-authored-by: Joshua Nelson <joshua@yottadb.com>

Clarify the literal string

ea70cc0

primitive impls are weird

ec966ae

Manishearth force-pushed the more-intra-doc branch from e9424e8 to ec966ae Compare July 19, 2020 05:42

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 19, 2020

Manishearth mentioned this pull request Jul 19, 2020

Rollup of 4 pull requests #74518

Merged

bors merged commit 1636961 into rust-lang:master Jul 19, 2020

jyn514 mentioned this pull request Nov 4, 2020

Broken links in String documentation from Deref impl #32129

Closed

cuviper added this to the 1.47.0 milestone May 2, 2024

	/// [`String::from`]: From::from
	/// [`String::from`]: #impl-From<%26%27_%20str>

	// https://github.com/rust-lang/rust/issues/62834 is necessary to be
	// https://github.com/rust-lang/rust/issues/63351 is necessary to be

Uh oh!

Conversation

Manishearth commented Jul 18, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rust-highfive commented Jul 18, 2020

Uh oh!

ollie27 commented Jul 18, 2020

Uh oh!

Manishearth commented Jul 18, 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!

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!

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!

Uh oh!

jyn514 commented Jul 19, 2020

Uh oh!

bors commented Jul 19, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Manishearth commented Jul 18, 2020 •

edited

Loading