Clean up in intra-doc link collector #77743

bugadani · 2020-10-09T10:06:18Z

This PR makes the following changes in intra-doc links:

clean up hard to follow closure-based logic in check_full_res
fix a FIXME comment by figuring out that true and false need to be resolved separately
refactor path resolution by extracting common code to a helper method and trying to reduce the number of unnecessary early returns
primitive types are now defined by their symbols, not their name strings
re-enables a commented-out test case

bugadani

I've found some parts of the code are hard to follow so I've done some cleanups, but it's not a thorough one. I don't really want to change anything big to not cause conflicts with ongoing PRs.

src/librustdoc/passes/collect_intra_doc_links.rs

jyn514 · 2020-10-09T15:39:14Z

Can you remove the first commit? I don't think this depends on #77700 in any way.

src/librustdoc/passes/collect_intra_doc_links.rs

bugadani · 2020-10-09T16:08:47Z

@jyn514 your test case can't compile, because true is a keyword.

/// [true] //~ ERROR ambiguous
pub mod true {}

Rustc recommends me r#-ing it, but then the test case ~~passes~~. No you are right, it doesn't report. I need to double check what I paste.

jyn514 · 2020-10-09T16:10:16Z

When you say passes, you mean it warns that it's an ambiguous link?

jyn514 · 2020-10-09T16:10:57Z

For context, this is teh current error on master:

warning: `true` is both a module and a builtin type
 --> tmp.rs:1:6
  |
1 | /// [true] ~ERROR ambiguous
  |      ^^^^ ambiguous link

jyn514 · 2020-10-09T17:32:51Z

Hmm, now try adding the disambiguator:

/// [primitive@true]
pub mod r#true {}

That goes through is_primitive, I think it will break after your change: https://github.com/rust-lang/rust/blob/5574fa0529401a8ff781e4017161f228b879c739/src/librustdoc/passes/collect_intra_doc_links.rs#L1011

bugadani · 2020-10-09T17:37:13Z

Well I added code to test for true and false, it's just uses is_bool_value now, so the new test case should resolve just fine.

jyn514 · 2020-10-09T17:38:13Z

I don't think we should separate is_primitive from is_true_and_false. I don't see any benefit to doing that, all it does is make you remember to call is_true_and_false() wherever you call is_primitive().

src/librustdoc/passes/collect_intra_doc_links.rs

jyn514

Thanks for working on this :)

src/librustdoc/passes/collect_intra_doc_links.rs

jyn514 · 2020-10-09T22:37:26Z

src/librustdoc/passes/collect_intra_doc_links.rs

-                Res::Def(DefKind::AssocTy, _) => false,
+        if let Ok(res) = result {
+            match res {
+                Res::Def(DefKind::AssocFn | DefKind::AssocConst, _) => {


I'm starting to wonder if traits_implemented_by is actually necessary ... do we already have the info here?
Related: #74489 (comment). Maybe rustc_resolve handles inherent impls but not anything else? @petrochenkov might know.

Anyway, not your problem to solve.

src/librustdoc/passes/collect_intra_doc_links.rs

jyn514 · 2020-10-09T22:44:23Z

src/librustdoc/passes/collect_intra_doc_links.rs

+fn is_bool_value(path_str: &str, ns: Namespace) -> Option<(&'static str, Res)> {
+    if ns == TypeNS && (path_str == "true" || path_str == "false") {
+        Some(("bool", Res::PrimTy(hir::PrimTy::Bool)))
    } else {
        None
    }


This looks a little out of place now that it's in its own function ... I'm starting to wonder if ollie was right in #75101 (comment).

Anyway, not your problem, the implementation looks fine.

Maybe we should support docs for keywords? :) /s

On second (and third) thought, is it correct to handle true and false as an alias of bool? They are values, not types, up until the point when somebody defines something else called true. But in that case, couldn't the built-in resolution handle them?

That's a separate policy decision that shouldn't happen here. I don't have a strong opinion either way, but if you want to change it please open a separate issue so we can discuss it separate from the implementation.

couldn't the built-in resolution handle them?

They're not really values, they're keywords. Typeck handles them specially IIRC.

src/test/rustdoc-ui/intra-links-ambiguity.rs

bugadani · 2020-10-10T12:13:51Z

The idea behind the ~~last 3~~ "Path resolution refactor", phase 1-3 commits is to make it clear that the resolution has two phases (not to be confused with the 3 part commit naming), and makes the phases as similar as possible.

I did not do this using purely equivalent transformations - instead of checking if we have a primitive, we first try to resolve the path instead, and only check primitiveness if we found a mod. I'm not sure if this can cause issues, but if it does, then the test suite does not cover it.

jyn514

Last few nits :) overall looks good

src/librustdoc/passes/collect_intra_doc_links.rs

jyn514 · 2020-10-10T19:36:06Z

src/librustdoc/passes/collect_intra_doc_links.rs

+        let ty_res = if let Some(ty_res) = is_primitive(&path_root, TypeNS)
+            .map(|(_, res)| res)
+            .or_else(|| self.resolve_path(&path_root, TypeNS, module_id))


After my spiel about separating refactors and changes, I don't want to make the change here, but I don't think these are both necessary:

Suggested change

let ty_res = if let Some(ty_res) = is_primitive(&path_root, TypeNS)

.map(|(_, res)| res)

.or_else(|| self.resolve_path(&path_root, TypeNS, module_id))

// FIXME: are these both necessary?

let ty_res = if let Some(ty_res) = is_primitive(&path_root, TypeNS)

.map(|(_, res)| res)

.or_else(|| self.resolve_path(&path_root, TypeNS, module_id))

In the strictest sense, they are, because removing is_primitive breaks tests, because modules aren't getting resolved. But even adding is_primitive back, it's only the modules that are called the same as the primitives that are... I wonder if this is because otherwise we'd end up returning early out of resolve()?

Let's fix this in a follow-up.

jyn514 · 2020-10-10T19:54:45Z

nit: Can you squash the commits a little more? No need to bring it down to one, but it would be nice not to have ' Undo the behaviour change while keeping most of the stylistic ones ' in the git history.

Either way, r=me.

@bors delegate=bugadani

bors · 2020-10-10T19:54:46Z

✌️ @bugadani can now approve this pull request

bugadani · 2020-10-10T19:55:45Z

I agree, but that is the trickiest commit to squash in the whole bunch because the changes are mixed with the str->symbol ones :) I'll see what I can do

jyn514 · 2020-10-10T19:56:32Z

Ok, no need then.

@bors r+

bors · 2020-10-10T19:56:33Z

📌 Commit d4c51b88f558ce4f38f0a4aae09a8fd8a1f055ce has been approved by jyn514

bugadani · 2020-10-10T20:02:02Z

Sorry for the last force push but it doesn't hurt if the patch builds. Also squashed the nasty bits. 2 in 1, but should be fine now!

jyn514 · 2020-10-10T20:13:51Z

@bors r+

bors · 2020-10-10T20:13:53Z

📌 Commit 46f183bf523d7ee2ead49b0c6f3e51290a63ff8e has been approved by jyn514

bors · 2020-10-10T23:57:15Z

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

Note that reviewers usually do not review pull requests until merge conflicts are resolved! Once you resolve the conflicts, you should change the labels applied by bors to indicate that your PR is ready for review. Post this as a comment to change the labels:

@rustbot modify labels: +S-waiting-on-review -S-waiting-on-author

bugadani · 2020-10-11T07:55:48Z

Rebased

@bors r+

bors · 2020-10-11T07:55:49Z

📌 Commit 725e3d1 has been approved by bugadani

bors · 2020-10-11T09:50:24Z

⌛ Testing commit 725e3d1 with merge c38f001...

bors · 2020-10-11T12:03:05Z

☀️ Test successful - checks-actions, checks-azure
Approved by: bugadani
Pushing c38f001 to master...

jyn514 · 2020-10-11T12:12:24Z

@bugadani small note - r+ marks you as the approver, please use r=jyn514 next time. Not a big deal though.

bugadani · 2020-10-11T12:13:23Z

Whoops, sorry about that. Is there a bors users' manual somewhere? :)

Actually, I found it here: https://buildbot2.rust-lang.org/homu/

bugadani commented Oct 9, 2020

View reviewed changes

src/librustdoc/passes/collect_intra_doc_links.rs Show resolved Hide resolved

bugadani force-pushed the idl-cleanup branch from 9f05679 to 0f11e97 Compare October 9, 2020 10:20

jyn514 added A-intra-doc-links Area: Intra-doc links, the ability to link to items in docs by name C-cleanup Category: PRs that clean code up or issues documenting cleanup. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Oct 9, 2020

jyn514 self-assigned this Oct 9, 2020

bugadani force-pushed the idl-cleanup branch from 0f11e97 to f030194 Compare October 9, 2020 15:40

jyn514 reviewed Oct 9, 2020

View reviewed changes

bugadani force-pushed the idl-cleanup branch 2 times, most recently from 31291db to 5574fa0 Compare October 9, 2020 16:20

bugadani commented Oct 9, 2020

View reviewed changes

src/librustdoc/passes/collect_intra_doc_links.rs Show resolved Hide resolved

jyn514 reviewed Oct 9, 2020

View reviewed changes

src/librustdoc/passes/collect_intra_doc_links.rs Outdated Show resolved Hide resolved

jyn514 mentioned this pull request Oct 9, 2020

rustdoc: intra doc links link to re-exported primitives #77757

Closed

jyn514 reviewed Oct 9, 2020

View reviewed changes

bugadani force-pushed the idl-cleanup branch 4 times, most recently from e532eb5 to 5c916d0 Compare October 10, 2020 11:42

bugadani force-pushed the idl-cleanup branch 2 times, most recently from 0b50831 to 4a22a57 Compare October 10, 2020 12:57

bugadani added 2 commits October 10, 2020 15:52

Clean up check_full_res

90e0fed

Clean up hard to follow control flow

3a640f2

bugadani force-pushed the idl-cleanup branch from e5144e4 to 8597dc2 Compare October 10, 2020 18:00

jyn514 approved these changes Oct 10, 2020

View reviewed changes

bugadani force-pushed the idl-cleanup branch from fd7f326 to d4c51b8 Compare October 10, 2020 19:50

bors added the S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. label Oct 10, 2020

bugadani force-pushed the idl-cleanup branch from d4c51b8 to 6727900 Compare October 10, 2020 20:00

bugadani force-pushed the idl-cleanup branch from 6727900 to 46f183b Compare October 10, 2020 20:05

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 Oct 10, 2020

bugadani force-pushed the idl-cleanup branch from 46f183b to 725e3d1 Compare October 11, 2020 07:34

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 Oct 11, 2020

bors added the merged-by-bors This PR was explicitly merged by bors. label Oct 11, 2020

bors merged commit c38f001 into rust-lang:master Oct 11, 2020

rustbot added this to the 1.49.0 milestone Oct 11, 2020

bugadani deleted the idl-cleanup branch October 11, 2020 12:03

Clean up in intra-doc link collector #77743

Clean up in intra-doc link collector #77743

Conversation

bugadani commented Oct 9, 2020 • edited by jyn514 Loading

bugadani left a comment • edited Loading

Choose a reason for hiding this comment

jyn514 commented Oct 9, 2020

bugadani commented Oct 9, 2020 • edited Loading

jyn514 commented Oct 9, 2020

jyn514 commented Oct 9, 2020

jyn514 commented Oct 9, 2020

bugadani commented Oct 9, 2020

jyn514 commented Oct 9, 2020 • edited Loading

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

Choose a reason for hiding this comment

bugadani commented Oct 10, 2020 • edited Loading

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

jyn514 commented Oct 10, 2020

bors commented Oct 10, 2020

bugadani commented Oct 10, 2020 • edited Loading

jyn514 commented Oct 10, 2020

bors commented Oct 10, 2020

bugadani commented Oct 10, 2020 • edited Loading

jyn514 commented Oct 10, 2020

bors commented Oct 10, 2020

bors commented Oct 10, 2020

bugadani commented Oct 11, 2020

bors commented Oct 11, 2020

bors commented Oct 11, 2020

bors commented Oct 11, 2020

jyn514 commented Oct 11, 2020

bugadani commented Oct 11, 2020 • edited Loading

bugadani commented Oct 9, 2020 •

edited by jyn514

Loading

bugadani left a comment •

edited

Loading

bugadani commented Oct 9, 2020 •

edited

Loading

jyn514 commented Oct 9, 2020 •

edited

Loading

bugadani commented Oct 10, 2020 •

edited

Loading

bugadani commented Oct 10, 2020 •

edited

Loading

bugadani commented Oct 10, 2020 •

edited

Loading

bugadani commented Oct 11, 2020 •

edited

Loading