Improve how rustdoc warnings are displayed

[GuillaumeGomez]

cc @rust-lang/dev-tools
r? @nrc

[QuietMisdreavus]

Doesn't look like it worked. I'm investigating the check_attributes function, it looks like it could be improved.

(context: this was meant to catch this issue, where the two sides only differ by an "id" attribute where either both are "name-N" or one is just "name" and the other is "name-1")

[QuietMisdreavus]

The following version of check_attributes works:

fn check_attributes(attrs1: &HashMap<String, String>, attrs2: &HashMap<String, String>) -> bool {
    /// For strings that match "something-N", returns "something", else returns the whole string
    fn extract_attr(value: &str) -> &str {
        let mut iter = value.rsplitn(2, '-');
        if let (Some(n), Some(tag)) = (iter.next(), iter.next()) {
            if n.parse::<usize>().is_ok() {
                tag
            } else {
                value
            }
        } else {
            value
        }
    }

    if let (Some(id1), Some(id2)) = (attrs1.get("id"), attrs2.get("id")) {
         let tag1 = extract_attr(id1);
         let tag2 = extract_attr(id2);

        tag1 == tag2
    } else {
        !attrs1.contains_key("id") && !attrs2.contains_key("id")
    }
}

[QuietMisdreavus]

On the other hand, even with that change, it still prints the warning, just now it doesn't print the actual difference. You'll need to float whether to print the warning at all out of render_difference so it doesn't print a worthless warning with no information on it.

[ollie27]

This isn't a false positive, it's just a bug in rustdoc. The issue is that by rendering the Markdown twice USED_ID_MAP gets updated twice for each id.

[GuillaumeGomez]

@ollie27: Yes, that's why we need to catch it (I precised it in the code change I think).
@QuietMisdreavus: Thanks! Updating the code.

[GuillaumeGomez]

Updated.

[QuietMisdreavus]

Fantastic! This cuts down on rendering warnings by an order of magnitude or more when rendering Rocket's dependencies (the first crate i checked).

@bors r+

[bors]

📌 Commit 884989a has been approved by QuietMisdreavus

[ollie27]

I've submitted a PR to actually fix the bug so that none of this is necessary: #44368.

[QuietMisdreavus]

Ooh, nice!

@bors r-

While i check out this other PR. The "don't print the warning heading" thing is still useful, but the bit about checking the header numbering may be better served with the new PR.

[GuillaumeGomez]

The second commit will still be relevant though. ;) (for other checks)

[QuietMisdreavus]

Since #44368 solves the "headers with diverging IDs" problem in a nicer fashion than the check introduced here, i want to pull that one in. However, like we've both said, this PR does more than that now. If you can yank out that first commit (good thinking, separating them like that 😛) and just keep the second one, we can make this PR focus on that instead.

[bors]

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

[alexcrichton]

@GuillaumeGomez ping to make sure this stays on your radar

[GuillaumeGomez]

@alexcrichton: We now need to confirm that the other PR made this one useless. Waiting for your confirmation @QuietMisdreavus! ;)

[QuietMisdreavus]

Yes, the bit that compared the IDs is superfluous now; #44368 took care of that. However, this PR as a whole isn't "useless", per se:

However, like we've both said, this PR does more than that now. If you can yank out that first commit (good thinking, separating them like that 😛) and just keep the second one, we can make this PR focus on that instead.

[GuillaumeGomez]

@QuietMisdreavus: Doing it!

[GuillaumeGomez]

Updated.

[QuietMisdreavus]

...i thought we agreed that check_attributes didn't need to be there any more >_>

[GuillaumeGomez]

Ah my bad, completely misunderstood. ><

[QuietMisdreavus]

The PR was patched up to take out the (now-superfluous) check_attributes, so now it's good. Strictly speaking, it's not really doing anything visible, but in case we find another false positive we need to filter out (and can't find other means to correct it) then this will be good to have.

@bors r+

[bors]

📌 Commit 7aa5367 has been approved by QuietMisdreavus

[bors]

⌛ Testing commit 7aa5367 with merge 5499683...

[bors]

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