Add lint for intra link resolution failure #51382

GuillaumeGomez · 2018-06-05T22:09:15Z

This PR is almost done, just remains this note:

note: requested on the command line with `-W intra-link-resolution-failure`

I have no idea why my lint is considered as being passed through command line and wasn't able to find where it was set. If anyone has an idea, it'd be very helpful!

cc @QuietMisdreavus

rust-highfive · 2018-06-05T22:09:18Z

r? @steveklabnik

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

killercup · 2018-06-06T07:58:35Z

Nice! Can you add a help text telling people how to escape stuff like "[The] quote was changed" so it doesn't warn and show the literal brackets?

GuillaumeGomez · 2018-06-06T08:16:20Z

Good idea!

GuillaumeGomez · 2018-06-09T15:31:17Z

@killercup: I added the help to escape the character.

Should be working fine now.

killercup · 2018-06-09T15:35:38Z

src/librustdoc/clean/mod.rs

    };
+    diag.help("to escape `[` and `]` characters, either put them into \"`[]`\" or \
+               use HTML values `&#91;` and `&#93;`");


I'd write

put them between back ticks (like "`[]`") or

Also, doesn't backslash escaping work, too?

It totally does haha. Just writing this then!

GuillaumeGomez · 2018-06-09T19:07:45Z

@killercup: What about this help message?

kennytm · 2018-06-09T20:43:51Z

src/librustdoc/clean/mod.rs

    };
+    diag.help("to escape `[` and `]` characters, just add '\\' before them like \
+               `\\[` or `\\]`");


I think this should better use span_suggestion here.

In many cases, it'll really be a link resolution failure. Not sure it'd be a nice idea to suggest that to remove the warning, they should not use auto-linking. :p

killercup · 2018-06-09T23:53:59Z

@GuillaumeGomez new help text is great, thanks!

QuietMisdreavus

A couple comments. I'm glad you got this working!

QuietMisdreavus · 2018-06-12T13:53:16Z

src/librustc/lint/builtin.rs

+declare_lint! {
+    pub INTRA_LINK_RESOLUTION_FAILURE,
+    Warn,
+    "warn about documentation intra links resolution failure"


I've tried to move away from calling this feature "intra links" because it doesn't mean much on its own. Instead, i've started opting for "type links". I feel like that says a bit more about the feature. What do you think?

As you prefer, I don't have a strong opinion on the naming.

intra links […] doesn't mean much on its own

What is this "intra links" thing you are talking about? Did you mean "intra doc links" which has actual context for what the links are between/within and for which we also have an RFC?

(And don't get me started on how these can also link to items that are, strictly speaking, not types!)

@QuietMisdreavus Why "type links"? It also works for functions and macros etc.

Soooooo, should I rename it? If so, how? :)

I have never, since the RFC was accepted, referred to this feature with its full title in internal discussions. The shortened title has been used so much that the full one has fallen out of our collective memory, as evidenced in this lint title, this PR title, and my comment here.

Calling it "type links" implies that it can link to "things that rustc cares about", even if the name is overly restrictive. Yes, i'm aware that the links can go to more than just "types".

INTRA_DOC_LINK_RESOLUTION_FAILURES is exceedingly verbose, but a quick look at rustc +nightly -W help says it's in good company, so use that.

QuietMisdreavus · 2018-06-12T13:59:41Z

src/librustc_lint/builtin.rs

+        lint_array!(
+            WHILE_TRUE,
+            BOX_POINTERS,
+            NON_SHORTHAND_FIELD_PATTERNS,


Where did this list of lints come from? I see a similar list in register_builtins farther down, but this one seems to be missing some of those.

From this file. :)

Aha, now i see it. Thanks for pointing that out.

QuietMisdreavus · 2018-06-12T14:15:24Z

src/libstd/sys/windows/ext/io.rs

@@ -10,6 +10,8 @@

 #![stable(feature = "rust1", since = "1.0.0")]

+//! Windows' IO module.


What are these Windows IO comments doing in a rustdoc PR?

It broke the build otherwise. There is a #![deny(missing_docs)] and rustdoc broke because of missing docs.

That shouldn't have happened. All of std::sys::windows (and std::os, where it's re-exported) should be covered by #[allow(missing_docs)]:

https://github.com/rust-lang/rust/blob/39061ff67033399390930b9e7703a2e9e8312ced/src/libstd/sys/windows/mod.rs#L11

https://github.com/rust-lang/rust/blob/39061ff67033399390930b9e7703a2e9e8312ced/src/libstd/os/mod.rs#L14

If not having these docs broke the build, that means we just broke #[allow(missing_docs)].

Interesting. I'll look further then.

Ok, the problem is a bit more complicated than that. Parser doesn't take into account windows mods and therefore doesn't apply its rules. However, rustdoc applies a cgf which it to access... ext! Therefore, ext doesn't have what the windows.rs has.

QuietMisdreavus · 2018-06-13T21:33:38Z

src/test/rustdoc-ui/deny-intra-link-resolution-failure.stderr

+   |
+11 | #![deny(intra_doc_link_resolution_failure)]
+   |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   = help: to escape `[` and `]` characters, just add '/' before them like `/[` or `/]`


Is this really how it comes out when the error appears? Or is it an artifact of the UI testing? It would be really worrying if we were accidentally suggesting the wrong thing.

EDIT: I mean it's showing a / when it should be showing a \, based on the help messages in the code above.

@QuietMisdreavus Just an artifact of UI test normalization.

Phew, i was getting nervous there. Imperio said he got the proper output when he ran the test locally, too, so i'll let this slide.

QuietMisdreavus

Sorry, last-minute thing i noticed.

QuietMisdreavus · 2018-06-13T23:49:38Z

src/librustdoc/core.rs

+        } else {
+            vec![]
+        },
+        lint_cap: Some(lint::Forbid),


Observation: lint_cap here is what was suppressing the compilation warnings that i mentioned in #41574 (comment). Changing this probably will make the --display-warnings flag useful on doc builds.

QuietMisdreavus · 2018-06-13T23:50:43Z

src/librustdoc/core.rs

+                    .filter_map(|lint| {
+                        if lint.name == warnings_lint_name ||
+                           lint.name == intra_link_resolution_failure_name {
+                            None


Do we really want to be excluding warnings in the lints being allowed here? It seems to be doing the opposite of the old code.

It's the opposite, we're allowing everything.

Are we sure that allowing a bunch of lints individually will act the same as allowing warnings all at once? Can we be sure that all warnings that can occur during a rustdoc run will always be placed in one of the lists you're chaining here?

If we set all warnings at once using this one, then the intra-doc lint stop working.

Ohhhhh, that makes sense, i forgot about that. In that case, this is fine.

QuietMisdreavus · 2018-06-14T18:05:16Z

@bors r+

kennytm · 2018-06-14T19:42:38Z

Legit failure

error: missing documentation for a type alias
  --> libstd\sys\unix/ext\raw.rs:21:49
   |
21 | #[stable(feature = "raw_ext", since = "1.1.0")] pub type uid_t = u32;
   |                                                 ^^^^^^^^^^^^^^^^^^^^^
   |
note: lint level defined here
  --> libstd\lib.rs:224:9
   |
224| #![deny(missing_docs)]
   |         ^^^^^^^^^^^^

@bors r-

GuillaumeGomez · 2018-06-15T07:59:23Z

Ah damn, same issue as windows.

GuillaumeGomez · 2018-06-15T10:03:29Z

Let's hope there won't be another platform failure...

@bors: r=QuietMisdreavus

bors · 2018-06-15T10:03:30Z

📌 Commit 6a03884 has been approved by QuietMisdreavus

bors · 2018-06-15T10:03:43Z

⌛ Testing commit 6a03884 with merge 3609834b0302af24ecf798e50ef6cd8b351f1b71...

bors · 2018-06-15T11:06:40Z

💔 Test failed - status-appveyor

GuillaumeGomez · 2018-06-15T12:26:24Z

clippy is failing to build? I'm not sure it's related to my changes this time...

cc @Manishearth

QuietMisdreavus · 2018-06-16T20:14:04Z

Clippy failing is expected. However, there were a few doctests in the reference and nomicon that failed?

3 command(s) did not execute successfully:
  - "C:\\projects\\rust\\build\\bootstrap/debug/rustdoc" "--test" "C:\\projects\\rust\\src/doc/nomicon\\src\\destructors.md" "--test-args" ""
  - "C:\\projects\\rust\\build\\bootstrap/debug/rustdoc" "--test" "C:\\projects\\rust\\src/doc/nomicon\\src\\vec-final.md" "--test-args" ""
  - "C:\\projects\\rust\\build\\bootstrap/debug/rustdoc" "--test" "C:\\projects\\rust\\src/doc/reference\\src\\expressions\\array-expr.md" "--test-args" ""

The failures in question

doc tests for: C:\projects\rust\src/doc/nomicon\src\destructors.md
running 6 tests
test C:\projects\rust\src/doc/nomicon\src\destructors.md - Destructors (line 28) ... FAILED
test C:\projects\rust\src/doc/nomicon\src\destructors.md - Destructors (line 54) ... FAILED
test C:\projects\rust\src/doc/nomicon\src\destructors.md - Destructors (line 6) ... ignored
test C:\projects\rust\src/doc/nomicon\src\destructors.md - Destructors (line 125) ... FAILED
test C:\projects\rust\src/doc/nomicon\src\destructors.md - Destructors (line 107) ... ok
test C:\projects\rust\src/doc/nomicon\src\destructors.md - Destructors (line 93) ... ok
failures:
---- C:\projects\rust\src/doc/nomicon\src\destructors.md - Destructors (line 28) stdout ----
error[E0599]: no method named `dealloc` found for type `std::alloc::Global` in the current scope
  --> C:\projects\rust\src/doc/nomicon\src\destructors.md:41:20
   |
14 |             Global.dealloc(self.ptr.as_ptr() as *mut _, Layout::new::<T>())
   |                    ^^^^^^^
   |
   = help: items from traits can only be used if the trait is in scope
help: the following trait is implemented but not in scope, perhaps add a `use` for it:
   |
4  | use std::alloc::Alloc;
   |
thread 'C:\projects\rust\src/doc/nomicon\src\destructors.md - Destructors (line 28)' panicked at 'couldn't compile the test', librustdoc\test.rs:325:17
note: Run with `RUST_BACKTRACE=1` for a backtrace.
---- C:\projects\rust\src/doc/nomicon\src\destructors.md - Destructors (line 54) stdout ----
error[E0599]: no method named `dealloc` found for type `std::alloc::Global` in the current scope
  --> C:\projects\rust\src/doc/nomicon\src\destructors.md:67:20
   |
14 |             Global.dealloc(self.ptr.as_ptr() as *mut _, Layout::new::<T>());
   |                    ^^^^^^^
   |
   = help: items from traits can only be used if the trait is in scope
help: the following trait is implemented but not in scope, perhaps add a `use` for it:
   |
4  | use std::alloc::Alloc;
   |
error[E0599]: no method named `dealloc` found for type `std::alloc::Global` in the current scope
  --> C:\projects\rust\src/doc/nomicon\src\destructors.md:79:20
   |
26 |             Global.dealloc(self.my_box.ptr.as_ptr() as *mut _, Layout::new::<T>());
   |                    ^^^^^^^
   |
   = help: items from traits can only be used if the trait is in scope
help: the following trait is implemented but not in scope, perhaps add a `use` for it:
   |
4  | use std::alloc::Alloc;
   |
thread 'C:\projects\rust\src/doc/nomicon\src\destructors.md - Destructors (line 54)' panicked at 'couldn't compile the test', librustdoc\test.rs:325:17
---- C:\projects\rust\src/doc/nomicon\src\destructors.md - Destructors (line 125) stdout ----
error[E0599]: no method named `dealloc` found for type `std::alloc::Global` in the current scope
  --> C:\projects\rust\src/doc/nomicon\src\destructors.md:138:20
   |
14 |             Global.dealloc(self.ptr.as_ptr() as *mut _, Layout::new::<T>());
   |                    ^^^^^^^
   |
   = help: items from traits can only be used if the trait is in scope
help: the following trait is implemented but not in scope, perhaps add a `use` for it:
   |
4  | use std::alloc::Alloc;
   |
error[E0599]: no method named `dealloc` found for type `std::alloc::Global` in the current scope
  --> C:\projects\rust\src/doc/nomicon\src\destructors.md:152:20
   |
28 |             Global.dealloc(my_box.ptr.as_ptr() as *mut _, Layout::new::<T>());
   |                    ^^^^^^^
   |
   = help: items from traits can only be used if the trait is in scope
help: the following trait is implemented but not in scope, perhaps add a `use` for it:
   |
4  | use std::alloc::Alloc;
   |
thread 'C:\projects\rust\src/doc/nomicon\src\destructors.md - Destructors (line 125)' panicked at 'couldn't compile the test', librustdoc\test.rs:325:17
failures:
    C:\projects\rust\src/doc/nomicon\src\destructors.md - Destructors (line 125)
    C:\projects\rust\src/doc/nomicon\src\destructors.md - Destructors (line 28)
    C:\projects\rust\src/doc/nomicon\src\destructors.md - Destructors (line 54)
test result: FAILED. 2 passed; 3 failed; 1 ignored; 0 measured; 0 filtered out

doc tests for: C:\projects\rust\src/doc/nomicon\src\vec-final.md
running 1 test
test C:\projects\rust\src/doc/nomicon\src\vec-final.md - The_Final_Code (line 3) ... FAILED
failures:
---- C:\projects\rust\src/doc/nomicon\src\vec-final.md - The_Final_Code (line 3) stdout ----
error[E0599]: no method named `alloc` found for type `std::alloc::Global` in the current scope
  --> C:\projects\rust\src/doc/nomicon\src\vec-final.md:37:34
   |
35 |                 let ptr = Global.alloc(Layout::array::<T>(1).unwrap());
   |                                  ^^^^^
   |
   = help: items from traits can only be used if the trait is in scope
help: the following trait is implemented but not in scope, perhaps add a `use` for it:
   |
6  | use std::alloc::Alloc;
   |
error[E0599]: no method named `realloc` found for type `std::alloc::Global` in the current scope
  --> C:\projects\rust\src/doc/nomicon\src\vec-final.md:41:34
   |
39 |                 let ptr = Global.realloc(self.ptr.as_ptr() as *mut _,
   |                                  ^^^^^^^
   |
   = help: items from traits can only be used if the trait is in scope
help: the following trait is implemented but not in scope, perhaps add a `use` for it:
   |
6  | use std::alloc::Alloc;
   |
error[E0061]: this function takes 1 parameter but 0 parameters were supplied
  --> C:\projects\rust\src/doc/nomicon\src\vec-final.md:49:17
   |
47 |                 oom()
   |                 ^^^^^ expected 1 parameter
error[E0599]: no method named `dealloc` found for type `std::alloc::Global` in the current scope
  --> C:\projects\rust\src/doc/nomicon\src\vec-final.md:63:24
   |
61 |                 Global.dealloc(self.ptr.as_ptr() as *mut _,
   |                        ^^^^^^^
   |
   = help: items from traits can only be used if the trait is in scope
help: the following trait is implemented but not in scope, perhaps add a `use` for it:
   |
6  | use std::alloc::Alloc;
   |
thread 'C:\projects\rust\src/doc/nomicon\src\vec-final.md - The_Final_Code (line 3)' panicked at 'couldn't compile the test', librustdoc\test.rs:325:17
note: Run with `RUST_BACKTRACE=1` for a backtrace.
failures:
    C:\projects\rust\src/doc/nomicon\src\vec-final.md - The_Final_Code (line 3)
test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out

doc tests for: C:\projects\rust\src/doc/reference\src\expressions\array-expr.md
running 2 tests
test C:\projects\rust\src/doc/reference\src\expressions\array-expr.md - Array_and_array_index_expressions::Array_and_slice_indexing_expressions (line 53) ... FAILED
test C:\projects\rust\src/doc/reference\src\expressions\array-expr.md - Array_and_array_index_expressions::Array_expressions (line 25) ... ok
failures:
---- C:\projects\rust\src/doc/reference\src\expressions\array-expr.md - Array_and_array_index_expressions::Array_and_slice_indexing_expressions (line 53) stdout ----
error: index out of bounds: the len is 2 but the index is 10
 --> C:\projects\rust\src/doc/reference\src\expressions\array-expr.md:59:9
  |
8 | let x = (["a", "b"])[10]; // warning: const index-expr is out of bounds
  |         ^^^^^^^^^^^^^^^^
  |
  = note: #[deny(const_err)] on by default
error: index out of bounds: the len is 2 but the index is 10
  --> C:\projects\rust\src/doc/reference\src\expressions\array-expr.md:65:1
   |
14 | arr[10];                  // panics
   | ^^^^^^^
thread 'C:\projects\rust\src/doc/reference\src\expressions\array-expr.md - Array_and_array_index_expressions::Array_and_slice_indexing_expressions (line 53)' panicked at 'couldn't compile the test', librustdoc\test.rs:325:17
note: Run with `RUST_BACKTRACE=1` for a backtrace.
failures:
    C:\projects\rust\src/doc/reference\src\expressions\array-expr.md - Array_and_array_index_expressions::Array_and_slice_indexing_expressions (line 53)
test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out

...but those also look like they should have been caught before this? Not totally sure what's going on.

kennytm · 2018-06-17T02:57:35Z

@bors retry

bors · 2018-06-17T02:57:46Z

⌛ Testing commit 6a03884 with merge 0f8f490...

@QuietMisdreavus

Add lint for intra link resolution failure This PR is almost done, just remains this note: ``` note: requested on the command line with `-W intra-link-resolution-failure` ``` I have no idea why my lint is considered as being passed through command line and wasn't able to find where it was set. If anyone has an idea, it'd be very helpful! cc @QuietMisdreavus

bors · 2018-06-17T04:55:52Z

☀️ Test successful - status-appveyor, status-travis
Approved by: QuietMisdreavus
Pushing 0f8f490 to master...

rust-highfive assigned steveklabnik Jun 5, 2018

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jun 5, 2018

This comment has been minimized.

Sign in to view

nrc mentioned this pull request Jun 6, 2018

Tracking issue for RFC 1946 - intra-rustdoc links #43466

Closed

27 tasks

This comment has been minimized.

Sign in to view

Add lint for intra link resolution failure

b000cf0

GuillaumeGomez force-pushed the intra-link-lint branch from 70ae786 to 6135267 Compare June 9, 2018 15:30

killercup reviewed Jun 9, 2018

View reviewed changes

This comment has been minimized.

Sign in to view

kennytm reviewed Jun 9, 2018

View reviewed changes

GuillaumeGomez force-pushed the intra-link-lint branch from a8edbc6 to 39061ff Compare June 9, 2018 21:22

QuietMisdreavus reviewed Jun 12, 2018

View reviewed changes

GuillaumeGomez added 4 commits June 13, 2018 21:18

Fix options issues

8c43c93

Add help for intra-link lint

2e343f3

Fix rustdoc test failure

6d5e6b4

Update help message to escape square brackets

e6c7868

GuillaumeGomez force-pushed the intra-link-lint branch from 4220ff4 to 3ab2f40 Compare June 13, 2018 20:28

GuillaumeGomez added 2 commits June 13, 2018 23:30

Rename intra-doc lint

d2a4e42

Add missing allow_missing_docs

231c61a

GuillaumeGomez force-pushed the intra-link-lint branch from 3ab2f40 to 231c61a Compare June 13, 2018 21:30

QuietMisdreavus reviewed Jun 13, 2018

View reviewed changes

bors added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Jun 14, 2018

Fix issue on unix

6a03884

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-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jun 15, 2018

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

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 Jun 17, 2018

bors merged commit 6a03884 into rust-lang:master Jun 17, 2018

This was referenced Jun 17, 2018

Add lint warning for inner function marked as #[test] #51450

Merged

Self in where clauses may not be object safe #50966

Merged

GuillaumeGomez deleted the intra-link-lint branch June 17, 2018 08:08

o01eg mentioned this pull request Jun 19, 2018

Rustdoc can not generate documentation for wasm32-unknown-unknown #51618

Closed

		@@ -10,6 +10,8 @@

		#![stable(feature = "rust1", since = "1.0.0")]

		//! Windows' IO module.

Add lint for intra link resolution failure #51382

Add lint for intra link resolution failure #51382

Conversation

GuillaumeGomez commented Jun 5, 2018

rust-highfive commented Jun 5, 2018

This comment has been minimized.

killercup commented Jun 6, 2018

GuillaumeGomez commented Jun 6, 2018

This comment has been minimized.

GuillaumeGomez commented Jun 9, 2018

killercup Jun 9, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

This comment has been minimized.

GuillaumeGomez commented Jun 9, 2018

This comment has been minimized.

Choose a reason for hiding this comment

Choose a reason for hiding this comment

killercup commented Jun 9, 2018

QuietMisdreavus left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

killercup Jun 12, 2018 • edited Loading

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

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

QuietMisdreavus Jun 13, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

QuietMisdreavus 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

Choose a reason for hiding this comment

QuietMisdreavus commented Jun 14, 2018

kennytm commented Jun 14, 2018 • edited Loading

GuillaumeGomez commented Jun 15, 2018

GuillaumeGomez commented Jun 15, 2018

bors commented Jun 15, 2018

bors commented Jun 15, 2018

bors commented Jun 15, 2018

GuillaumeGomez commented Jun 15, 2018

QuietMisdreavus commented Jun 16, 2018

kennytm commented Jun 17, 2018

bors commented Jun 17, 2018

bors commented Jun 17, 2018

killercup Jun 9, 2018 •

edited

Loading

killercup Jun 12, 2018 •

edited

Loading

QuietMisdreavus Jun 13, 2018 •

edited

Loading

kennytm commented Jun 14, 2018 •

edited

Loading