[WIP] Intra-doc links side of warning about undocumented items #82014

jyn514 · 2021-02-12T02:53:36Z

Unfortunately, this currently breaks because the cache is not populated
until later, so rustdoc thinks some items won't be documented when they
will be. Hoping to fix that separately, but opening this first so I don't forget about it.

Fixes #81979.

r? @ghost

bors · 2021-02-12T18:15:17Z

☔ The latest upstream changes (presumably #82025) made this pull request unmergeable. Please resolve the merge conflicts.

bugadani · 2021-02-12T22:24:20Z

src/test/rustdoc-ui/intra-doc/anchors.stderr

+  --> $DIR/anchors.rs:23:11
+   |
+LL | /// Like [Foo#hola].
+   |           ^^^^^^^^ this item is will not be documented


is will not be sounds fishy :)

camelid · 2021-02-16T20:59:34Z

src/librustdoc/passes/collect_intra_doc_links.rs

+        use crate::clean::types::{AttributesExt, NestedAttributesExt};
+
+        if let Some(sp) = sp {
+            diag.span_label(sp, "this item is will not be documented");


Suggested change

diag.span_label(sp, "this item is will not be documented");

diag.span_label(sp, "this item is private and will not be documented");

"private" isn't correct, there are many reasons it might not be documented (e.g. it's a public export of a private item marked with no_inline; crate is masked; --extern-html-url wasn't passed).

jyn514 · 2021-02-17T00:19:02Z

FYI this is very broken currently and needs major refactors to rustdoc before merging, so I wouldn't bother looking at the typos and such just yet.

…eGomez Make `Clean` take &mut DocContext - Take `FnMut` in `rustc_trait_selection::find_auto_trait_generics` - Take `&mut DocContext` in most of `clean` - Collect the iterator in auto_trait_impls instead of iterating lazily; the lifetimes were really bad. This combined with rust-lang#82018 should hopefully help with rust-lang#82014 by allowing `cx.cache.exported_traits` to be modified in `register_res`. Previously it had to use interior mutability, which required either adding a RefCell to `cache.exported_traits` on *top* of the existing `RefCell<Cache>` or mixing reads and writes between `cx.exported_traits` and `cx.cache.exported_traits`. I don't currently have that working but I expect it to be reasonably easy to add after this.

…illaumeGomez Remove the dummy cache in `DocContext`; delete RenderInfo The same information is available everywhere; the only reason the dummy cache was needed is because it was previously stored in three different places. This consolidates the info a bit so the cache in `DocContext` is used throughout. As a bonus, it also completely removes `RenderInfo`. - Return a `Cache` from `run_global_ctxt`, not `RenderInfo` - Remove the unused `render_info` from `run_renderer` - Remove RenderInfo altogether Helps with rust-lang#82014. The next step is to move the `populate()` call before the `collect_intra_doc_links` pass, which currently breaks because a) lots of the cache is populated in early passes, and b) intra_doc_links itself sets some info with `register_res`. I'm working on separate PR for that to avoid making too many big changes at once. r? `@GuillaumeGomez`

camelid · 2021-03-12T04:14:13Z

I'm wondering if this might no longer be blocked given that #82018 has been merged?

jyn514 · 2021-03-12T21:45:38Z

@camelid this isn't blocked on anything in particular, I just need to figure out whether it's possible to make it work in the intra-doc pass itself or whether it has to be delayed until later when less diagnostic info is available (but more cache info is populated).

JohnCSimon · 2021-05-31T04:49:58Z

triage:
@jyn514 Can you post your status on this PR? Is it still WIP?

jyn514 · 2021-05-31T21:33:36Z

@JohnCSimon same status as in #82014 (comment). I don't know when I'll get a chance to work on it.

jyn514 · 2022-03-26T06:39:01Z

src/librustdoc/passes/collect_intra_doc_links.rs

+        }
+
+        // NOTE: theoretically it shouldn't be possible to resolve private items,
+        // but `resolve_primitive_associated_item` is buggy and allows it.


This comment is wrong - the actual issue is that primitive associated items are always reachable, but href doesn't take that into account

Before: ``` Item { name: Some("Send"), attrs: Attributes { doc_strings: [DocFragment { span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:15:1: 15:60 (#0), parent_module: None, doc: " Types that can be transferred across thread boundaries.", kind: SugaredDoc, indent: 1 }, DocFragment { span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:16:1: 16:4 (#0), parent_module: None, doc: "", kind: SugaredDoc, indent: 0 }, DocFragment { span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:17:1: 17:78 (#0), parent_module: None, doc: " This trait is automatically implemented when the compiler determines it's", kind: SugaredDoc, indent: 1 }, DocFragment { span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:18:1: 18:17 (#0), parent_module: None, doc: " appropriate.", kind: SugaredDoc, indent: 1 }, DocFragment { span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:19:1: 19:4 (#0), parent_module: None, doc: "", kind: SugaredDoc, indent: 0 }, DocFragment { span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:20:1: 20:70 (#0), parent_module: None, doc: " An example of a non-`Send` type is the reference-counting pointer", kind: SugaredDoc, indent: 1 }, DocFragment { span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:21:1: 21:85 (#0), parent_module: None, doc: " [`rc::Rc`][`Rc`]. If two threads attempt to clone [`Rc`]s that point to the same", kind: SugaredDoc, indent: 1 }, DocFragment { span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:22:1: 22:81 (#0), parent_module: None, doc: " reference-counted value, they might try to update the reference count at the", kind: SugaredDoc, indent: 1 }, DocFragment { span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:23:1: 23:83 (#0), parent_module: None, doc: " same time, which is [undefined behavior][ub] because [`Rc`] doesn't use atomic", kind: SugaredDoc, indent: 1 }, DocFragment { span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:24:1: 24:84 (#0), parent_module: None, doc: " operations. Its cousin [`sync::Arc`][arc] does use atomic operations (incurring", kind: SugaredDoc, indent: 1 }, DocFragment { span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:25:1: 25:39 (#0), parent_module: None, doc: " some overhead) and thus is `Send`.", kind: SugaredDoc, indent: 1 }, DocFragment { span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:26:1: 26:4 (#0), parent_module: None, doc: "", kind: SugaredDoc, indent: 0 }, DocFragment { span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:27:1: 27:74 (#0), parent_module: None, doc: " See [the Nomicon](../../nomicon/send-and-sync.html) for more details.", kind: SugaredDoc, indent: 1 }, DocFragment { span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:28:1: 28:4 (#0), parent_module: None, doc: "", kind: SugaredDoc, indent: 0 }, DocFragment { span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:29:1: 29:40 (#0), parent_module: None, doc: " [`Rc`]: ../../std/rc/struct.Rc.html", kind: SugaredDoc, indent: 1 }, DocFragment { span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:30:1: 30:42 (#0), parent_module: None, doc: " [arc]: ../../std/sync/struct.Arc.html", kind: SugaredDoc, indent: 1 }, DocFragment { span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:31:1: 31:61 (#0), parent_module: None, doc: " [ub]: ../../reference/behavior-considered-undefined.html", kind: SugaredDoc, indent: 1 }], other_attrs: [Attribute { kind: Normal(AttrItem { path: Path { span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:32:3: 32:9 (#0), segments: [PathSegment { ident: stable#0, id: NodeId(33577), args: None }], tokens: None }, args: Delimited(DelimSpan { open: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:32:9: 32:10 (#0), close: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:32:44: 32:45 (#0) }, Parenthesis, TokenStream([(Token(Token { kind: Ident("feature", false), span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:32:10: 32:17 (#0) }), Alone), (Token(Token { kind: Eq, span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:32:18: 32:19 (#0) }), Alone), (Token(Token { kind: Literal(Lit { kind: Str, symbol: "rust1", suffix: None }), span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:32:20: 32:27 (#0) }), Joint), (Token(Token { kind: Comma, span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:32:27: 32:28 (#0) }), Alone), (Token(Token { kind: Ident("since", false), span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:32:29: 32:34 (#0) }), Alone), (Token(Token { kind: Eq, span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:32:35: 32:36 (#0) }), Alone), (Token(Token { kind: Literal(Lit { kind: Str, symbol: "1.0.0", suffix: None }), span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:32:37: 32:44 (#0) }), Alone)])), tokens: None }, None), id: AttrId(48), style: Outer, span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:32:1: 32:46 (#0) }, Attribute { kind: Normal(AttrItem { path: Path { span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:33:23: 33:44 (#0), segments: [PathSegment { ident: rustc_diagnostic_item#0, id: NodeId(33578), args: None }], tokens: None }, args: Eq(/rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:33:45: 33:46 (#0), Token { kind: Literal(Lit { kind: Str, symbol: "Send", suffix: None }), span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:33:47: 33:53 (#0) }), tokens: None }, None), id: AttrId(49), style: Outer, span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:33:23: 33:53 (#0) }, Attribute { kind: Normal(AttrItem { path: Path { span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:34:3: 34:25 (#0), segments: [PathSegment { ident: rustc_on_unimplemented#0, id: NodeId(33580), args: None }], tokens: None }, args: Delimited(DelimSpan { open: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:34:25: 34:26 (#0), close: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:37:1: 37:2 (#0) }, Parenthesis, TokenStream([(Token(Token { kind: Ident("message", false), span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:35:5: 35:12 (#0) }), Alone), (Token(Token { kind: Eq, span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:35:13: 35:14 (#0) }), Alone), (Token(Token { kind: Literal(Lit { kind: Str, symbol: "`{Self}` cannot be sent between threads safely", suffix: None }), span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:35:15: 35:63 (#0) }), Joint), (Token(Token { kind: Comma, span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:35:63: 35:64 (#0) }), Alone), (Token(Token { kind: Ident("label", false), span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:36:5: 36:10 (#0) }), Alone), (Token(Token { kind: Eq, span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:36:11: 36:12 (#0) }), Alone), (Token(Token { kind: Literal(Lit { kind: Str, symbol: "`{Self}` cannot be sent between threads safely", suffix: None }), span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:36:13: 36:61 (#0) }), Alone)])), tokens: None }, None), id: AttrId(50), style: Outer, span: /rustc/37b55c8a0cafdb60b9168da34f904acc70157df8/library/core/src/marker.rs:34:1: 37:3 (#0) }] }, visibility: Public, kind: TraitItem(Trait { unsafety: Unsafe, items: [], generics: Generics { params: [], where_predicates: [] }, bounds: [], is_auto: true }), def_id: DefId(DefId(2:3027 ~ core[7f4a]::marker::Send)), cfg: None } ``` After: ``` Item { name: Some("Send"), visibility: Public, def_id: DefId(DefId(2:3027 ~ core[7f4a]::marker::Send)), kind: Trait, docs: "Types that can be transferred across thread boundaries.\n\nThis trait is automatically implemented when the compiler determines it's\nappropriate.\n\nAn example of a non-`Send` type is the reference-counting pointer\n[`rc::Rc`][`Rc`]. If two threads attempt to clone [`Rc`]s that point to the same\nreference-counted value, they might try to update the reference count at the\nsame time, which is [undefined behavior][ub] because [`Rc`] doesn't use atomic\noperations. Its cousin [`sync::Arc`][arc] does use atomic operations (incurring\nsome overhead) and thus is `Send`.\n\nSee [the Nomicon](../../nomicon/send-and-sync.html) for more details.\n\n[`Rc`]: ../../std/rc/struct.Rc.html\n[arc]: ../../std/sync/struct.Arc.html\n[ub]: ../../reference/behavior-considered-undefined.html" } ```

Unfortunately, this currently breaks because the cache is not populated until later, so rustdoc thinks some items won't be documented when they will be. - Track why links are missing - Populate cache before running pass

aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaahhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh this is so curseeeeeeed currently failing: - rustdoc/doc-cfg-simplification.rs - rustdoc/intra-doc-crate/self.rs

rust-log-analyzer · 2022-03-27T03:10:36Z

The job mingw-check failed! Check out the build log: (web) (plain)

Click to see the possible cause of the failure (guessed by this bot)

configure: rust.debug-assertions := True
configure: rust.overflow-checks := True
configure: llvm.assertions      := True
configure: dist.missing-tools   := True
configure: build.configure-args := ['--enable-sccache', '--disable-manage-submodu ...
configure: writing `config.toml` in current directory
configure: 
configure: run `python /checkout/x.py --help`
configure: 
---
tidy: Skipping binary file check, read-only filesystem
Checking which error codes lack tests...
* 629 error codes
* highest error code: E0787
tidy error: /checkout/src/test/rustdoc-ui/intra-doc/warn-undocumented.rs: missing trailing newline
Found 0 error(s) in error codes
Done!
* 371 features
some tidy checks failed

bors · 2022-04-01T21:03:59Z

☔ The latest upstream changes (presumably #95552) made this pull request unmergeable. Please resolve the merge conflicts.

JohnCSimon · 2022-11-27T02:16:58Z

@jyn514
Ping from triage: I'm closing this due to inactivity, Please reopen when you are ready to continue with this.
Note: if you do please open the PR BEFORE you push to it, else you won't be able to reopen - this is a quirk of github.
Thanks for your contribution.

@rustbot label: +S-inactive

This comment has been minimized.

Sign in to view

This was referenced Feb 12, 2021

Remove the dummy cache in DocContext; delete RenderInfo #82018

Merged

Make Clean take &mut DocContext #82020

Merged

bugadani reviewed Feb 12, 2021

View reviewed changes

camelid reviewed Feb 16, 2021

View reviewed changes

jyn514 changed the title ~~Intra-doc links side of warning about undocumented items~~ [WIP] Intra-doc links side of warning about undocumented items Feb 26, 2021

jyn514 added S-experimental Status: Ongoing experiment that does not require reviewing and won't be merged in its current state. and removed S-blocked Status: Blocked on something else such as an RFC or other implementation work. labels Mar 12, 2021

jyn514 force-pushed the warn-hidden branch 2 times, most recently from f581c3d to 0f36c80 Compare March 12, 2021 22:15

This comment has been minimized.

Sign in to view

crlf0710 removed the S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. label Jun 19, 2021

crlf0710 marked this pull request as draft June 19, 2021 12:56

jyn514 mentioned this pull request Jun 27, 2021

fix dead link for method in trait of blanket impl from third party crate #86662

Merged

jyn514 force-pushed the warn-hidden branch from e99d8ed to 1e78618 Compare July 3, 2021 03:55

This comment has been minimized.

Sign in to view

jyn514 force-pushed the warn-hidden branch from 1e78618 to 8f9be18 Compare March 26, 2022 05:36

This comment has been minimized.

Sign in to view

jyn514 force-pushed the warn-hidden branch from 8f9be18 to 01bafd7 Compare March 26, 2022 06:05

This comment has been minimized.

Sign in to view

jyn514 force-pushed the warn-hidden branch from 01bafd7 to 980f458 Compare March 26, 2022 06:18

This comment has been minimized.

Sign in to view

jyn514 commented Mar 26, 2022

View reviewed changes

jyn514 and others added 5 commits March 26, 2022 15:46

Intra-doc links side of warning about undocumented items

2ef5570

Unfortunately, this currently breaks because the cache is not populated until later, so rustdoc thinks some items won't be documented when they will be. - Track why links are missing - Populate cache before running pass

fix some tests lolzzzzz

b9085ad

[wip] try to process impl blocks in collect pass

53d7f95

aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaahhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh this is so curseeeeeeed currently failing: - rustdoc/doc-cfg-simplification.rs - rustdoc/intra-doc-crate/self.rs

fix impl blocks

f6419c7

jyn514 force-pushed the warn-hidden branch from 980f458 to f6419c7 Compare March 26, 2022 21:24

fix tidy so ci is useful again

7531753

jyn514 force-pushed the warn-hidden branch from 534079d to 7531753 Compare March 26, 2022 21:28

jyn514 added 2 commits March 26, 2022 16:35

it all works!@!!!!

17f1a53

add test case and fix one last test

d33d014

bors added the S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. label Apr 1, 2022

JohnCSimon closed this Nov 27, 2022

rustbot added the S-inactive Status: Inactive and waiting on the author. This is often applied to closed PRs. label Nov 27, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[WIP] Intra-doc links side of warning about undocumented items #82014

[WIP] Intra-doc links side of warning about undocumented items #82014

jyn514 commented Feb 12, 2021

This comment has been minimized.

bors commented Feb 12, 2021

bugadani Feb 12, 2021

camelid Feb 16, 2021

jyn514 Mar 26, 2022

jyn514 commented Feb 17, 2021

camelid commented Mar 12, 2021

jyn514 commented Mar 12, 2021

This comment has been minimized.

JohnCSimon commented May 31, 2021

jyn514 commented May 31, 2021

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

jyn514 Mar 26, 2022

rust-log-analyzer commented Mar 27, 2022

bors commented Apr 1, 2022

JohnCSimon commented Nov 27, 2022

	diag.span_label(sp, "this item is will not be documented");
	diag.span_label(sp, "this item is private and will not be documented");

[WIP] Intra-doc links side of warning about undocumented items #82014

[WIP] Intra-doc links side of warning about undocumented items #82014

Conversation

jyn514 commented Feb 12, 2021

This comment has been minimized.

bors commented Feb 12, 2021

bugadani Feb 12, 2021

Choose a reason for hiding this comment

camelid Feb 16, 2021

Choose a reason for hiding this comment

jyn514 Mar 26, 2022

Choose a reason for hiding this comment

jyn514 commented Feb 17, 2021

camelid commented Mar 12, 2021

jyn514 commented Mar 12, 2021

This comment has been minimized.

JohnCSimon commented May 31, 2021

jyn514 commented May 31, 2021

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

jyn514 Mar 26, 2022

Choose a reason for hiding this comment

rust-log-analyzer commented Mar 27, 2022

bors commented Apr 1, 2022

JohnCSimon commented Nov 27, 2022