Use intra-doc links in core::iter module #74300

tesuji · 2020-07-13T16:28:48Z

This will make core::iter doc depend less on std doc.

rust-highfive · 2020-07-13T16:28:51Z

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

lcnr · 2020-07-13T16:56:20Z

This would result in dead links in std due to #65983, also see #73579 (comment) where I personally first noticed this problem.

pickfire · 2020-07-13T17:41:44Z

src/libcore/iter/traits/accum.rs

-/// [`sum`]: ../../std/iter/trait.Sum.html#tymethod.sum
-/// [`FromIterator`]: ../../std/iter/trait.FromIterator.html
-/// [`Iterator::sum`]: ../../std/iter/trait.Iterator.html#method.sum
+/// [`sum`]: #tymethod.sum


Does this not have an equivalent?

This fragment link is fine as the sum method referred belongs to Sum trait.

This is #51284, which is a project all on its own. If @lzutao checked that it works I'm fine with it.

Can this not be Sum::sum or Self::sum?

Is it documented in Intra RFC? That's new to me!

tesuji · 2020-07-14T02:38:54Z

@lcnr I don't quite sure there are any broken links as linkchecker doesn't warn.
Also I don't use cross-crate links (I think), only crate:: prefix links.
cc @jyn514 to make sure.

jyn514 · 2020-07-14T03:06:50Z

I'm pretty sure core is re-exported as part of std, so that could break things. You should check locally to be sure.

jyn514 · 2020-07-14T03:07:30Z

As a side note, #73101 is almost ready to be merged, maybe 1 or 2 more weeks.

tesuji · 2020-07-14T04:34:21Z

Checked locally and ran linkchecker. I don't see any broken links
in both std and core.

lcnr · 2020-07-14T08:14:05Z

tesuji · 2020-07-14T08:16:11Z

~~Pardon me?~~
Edit: Oh, I see it now. Option is not linked. I will see what I can do to fix the links.

tesuji · 2020-07-14T11:22:14Z

After experimenting, I observed two things:

Replacing [`Option`] in core::iter with crate::option::Option broke the link.
Letting rustdoc handle Option link (no manually specify link), rustdoc doesn't make link or warn about that.

The broke links are detected by linkchecker. I don't know if there are more empty-links,
but this PR shouldn't broke links.

jyn514 · 2020-07-17T03:37:21Z

This would result in dead links in std due to #65983, also see #73579 (comment) where I personally first noticed this problem.

#73101 just landed so this should be fixed once you rebase 😄 You'll need to use x.py doc --stage 1 to get the changes.

tesuji · 2020-07-17T06:00:32Z

Rebased. Looks like stage1 rustdoc fixes the Option link in core::iter .
r? @jyn514

jyn514

Looks great! It's good to see how this is used in the wild, it gave me ideas for more features to add 😆 I had one small nit but everything else is informative or notes to myself.

src/libcore/iter/traits/iterator.rs

jyn514 · 2020-07-17T11:17:20Z

src/libcore/iter/traits/iterator.rs

-    /// [`Option<T>`]: ../../std/option/enum.Option.html
-    /// [`Some`]: ../../std/option/enum.Option.html#variant.Some
-    /// [`None`]: ../../std/option/enum.Option.html#variant.None
+    /// [`Option<T>`]: Option


This is #62834. This is a good workaround in the meantime though.

But why not just use Option rather than Option<T>?

Option<T> seems to be clearer for beginners/first readers of Iterator.

We could use Option<T> in the book, but I don't think beginners get here easily.

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

src/libcore/iter/traits/iterator.rs

@@ -1366,8 +1350,7 @@ pub trait Iterator {
    /// [`Some(T)`] again. `fuse()` adapts an iterator, ensuring that after a
    /// [`None`] is given, it will always return [`None`] forever.
    ///
-    /// [`None`]: ../../std/option/enum.Option.html#variant.None
-    /// [`Some(T)`]: ../../std/option/enum.Option.html#variant.Some
+    /// [`Some(T)`]: Some


I've seen this quite a few times now, maybe it would be a good feature for intra-doc links to add, same as #62834?

jyn514 · 2020-07-17T11:27:27Z

ran linkchecker. I don't see any broken links

#74185 (comment). Maybe we should add deny(intra_doc_link_resolutuion_failure) now that cross crate re-exports work?

Because the old one is harder to read and confuse typing checkers.

jyn514 · 2020-07-17T14:26:29Z

Maybe we should add deny(intra_doc_link_resolutuion_failure) now that cross crate re-exports work?

It turns out this will be on by default starting in #71670. But it doesn't hurt to have it on now.

jyn514 · 2020-07-17T14:28:01Z

r=me, but I don't have bors permissions until rust-lang/team#384 lands.

jyn514 · 2020-07-17T14:38:47Z

@bors r+ rollup

bors · 2020-07-17T14:38:49Z

@jyn514: 🔑 Insufficient privileges: Not in reviewers

lcnr · 2020-07-17T14:41:51Z

@bors r=jyn514 rollup=always

bors · 2020-07-17T14:41:52Z

📌 Commit 5ffdd7c has been approved by jyn514

Use intra-doc links in core::iter module This will make core::iter doc depend less on std doc.

@ghost

…arth Rollup of 18 pull requests Successful merges: - rust-lang#71670 (Enforce even more the code blocks attributes check through rustdoc) - rust-lang#73930 (Make some Option methods const) - rust-lang#74009 (Fix MinGW `run-make-fulldeps` tests) - rust-lang#74056 (Add Arguments::as_str().) - rust-lang#74169 (Stop processing unreachable blocks when solving dataflow) - rust-lang#74251 (Teach bootstrap about target files vs target triples) - rust-lang#74288 (Fix src/test/run-make/static-pie/test-aslr.rs) - rust-lang#74300 (Use intra-doc links in core::iter module) - rust-lang#74364 (add lazy normalization regression tests) - rust-lang#74368 (Add CSS tidy check) - rust-lang#74394 (Remove leftover from emscripten fastcomp support) - rust-lang#74411 (Don't assign `()` to `!` MIR locals) - rust-lang#74416 (Use an UTF-8 locale for the linker.) - rust-lang#74424 (Move hir::Place to librustc_middle/hir) - rust-lang#74428 (docs: better demonstrate that None values are skipped as many times a…) - rust-lang#74438 (warn about uninitialized multi-variant enums) - rust-lang#74440 (Fix Arc::as_ptr docs) - rust-lang#74452 (intra-doc links: resolve modules in the type namespace) Failed merges: r? @ghost

rust-highfive assigned withoutboats Jul 13, 2020

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

pickfire reviewed Jul 13, 2020

View reviewed changes

tesuji force-pushed the iterator-intra branch from db2f8fc to 5da4c02 Compare July 17, 2020 05:54

rust-highfive assigned jyn514 and unassigned withoutboats Jul 17, 2020

jyn514 approved these changes Jul 17, 2020

View reviewed changes

tesuji added 7 commits July 17, 2020 13:00

Use intra-doc link on Iterator page

91738d8

Intra doc for iter marker traits

53a1d6f

Intra-doc for DoubleEndIterator

69f43dd

Intra-doc for iter Sum and Product traits

a7f067a

Remove unneeded link for Option

3fb3c0c

Link Some(item)

1a90ba7

Remove code span for impl

67c1e89

Because the old one is harder to read and confuse typing checkers.

tesuji force-pushed the iterator-intra branch from 5da4c02 to 5d3c4c0 Compare July 17, 2020 13:15

Deny intra_doc_link_resolution_failure in libcore

5ffdd7c

tesuji force-pushed the iterator-intra branch from 5d3c4c0 to 5ffdd7c Compare July 17, 2020 13:25

jyn514 mentioned this pull request Jul 17, 2020

Allow generic parameters in intra doc link #62834

Closed

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 added a commit to Manishearth/rust that referenced this pull request Jul 17, 2020

Rollup merge of rust-lang#74300 - lzutao:iterator-intra, r=jyn514

966d33c

Use intra-doc links in core::iter module This will make core::iter doc depend less on std doc.

Manishearth mentioned this pull request Jul 17, 2020

Rollup of 17 pull requests #74455

Closed

Manishearth mentioned this pull request Jul 17, 2020

Rollup of 18 pull requests #74461

Merged

bors merged commit c9010d6 into rust-lang:master Jul 18, 2020

tesuji deleted the iterator-intra branch July 18, 2020 02:12

jyn514 mentioned this pull request Jul 30, 2020

Rename intra_doc_link_resolution_failure #74926

Merged

cuviper added this to the 1.47.0 milestone May 2, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Use intra-doc links in core::iter module #74300

Use intra-doc links in core::iter module #74300

tesuji commented Jul 13, 2020

rust-highfive commented Jul 13, 2020

lcnr commented Jul 13, 2020

pickfire Jul 13, 2020

tesuji Jul 14, 2020 •

edited

Loading

jyn514 Jul 17, 2020

Manishearth Jul 17, 2020

tesuji Jul 18, 2020 •

edited

Loading

tesuji commented Jul 14, 2020

jyn514 commented Jul 14, 2020

jyn514 commented Jul 14, 2020

tesuji commented Jul 14, 2020 •

edited

Loading

lcnr commented Jul 14, 2020

tesuji commented Jul 14, 2020 •

edited

Loading

tesuji commented Jul 14, 2020

jyn514 commented Jul 17, 2020

tesuji commented Jul 17, 2020

jyn514 left a comment

jyn514 Jul 17, 2020

pickfire Jul 17, 2020

tesuji Jul 18, 2020

pickfire Jul 18, 2020

jyn514 Jul 17, 2020

jyn514 commented Jul 17, 2020

jyn514 commented Jul 17, 2020

jyn514 commented Jul 17, 2020

jyn514 commented Jul 17, 2020

bors commented Jul 17, 2020

lcnr commented Jul 17, 2020

bors commented Jul 17, 2020

Use intra-doc links in core::iter module #74300

Use intra-doc links in core::iter module #74300

Conversation

tesuji commented Jul 13, 2020

rust-highfive commented Jul 13, 2020

lcnr commented Jul 13, 2020

Choose a reason for hiding this comment

tesuji Jul 14, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tesuji Jul 18, 2020 • edited Loading

Choose a reason for hiding this comment

tesuji commented Jul 14, 2020

jyn514 commented Jul 14, 2020

jyn514 commented Jul 14, 2020

tesuji commented Jul 14, 2020 • edited Loading

lcnr commented Jul 14, 2020

tesuji commented Jul 14, 2020 • edited Loading

tesuji commented Jul 14, 2020

jyn514 commented Jul 17, 2020

tesuji commented Jul 17, 2020

jyn514 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jyn514 commented Jul 17, 2020

jyn514 commented Jul 17, 2020

jyn514 commented Jul 17, 2020

jyn514 commented Jul 17, 2020

bors commented Jul 17, 2020

lcnr commented Jul 17, 2020

bors commented Jul 17, 2020

tesuji Jul 14, 2020 •

edited

Loading

tesuji Jul 18, 2020 •

edited

Loading

tesuji commented Jul 14, 2020 •

edited

Loading

tesuji commented Jul 14, 2020 •

edited

Loading