rustdoc: remove the ! from macro URLs and titles

[nrc]

Because the ! is part of a macro use, not the macro's name. E.g., you write macro_rules! foo not macro_rules! foo!, also #[macro_import(foo)].

(Pulled out of #35020).

[rust-highfive]

r? @steveklabnik

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

[nrc]

cc @alexcrichton

[alexcrichton]

Sounds good to me! @steveklabnik what do you think?

[ollie27]

I don't think we can change the URLs because it will break links.

We could change the titles but it brings up an interesting point about how we refer to macros. For instance on the page for std::fmt almost every reference to a macro includes the !.

[nrc]

I don't mind breaking a few links, I don't think it will be a huge impact. I'd be fine with adding redirects, but with no warnings, that is just pushing the breakage down the road, unless we want to leave the redirects forever (which I guess is not too bad).

[steveklabnik]

I like the idea, but also share concern about breaking things.

Across all these PRs, I have no idea what the "right" thing is; at some point, we will have to break stuff. It'd be kinda nice to do it all at once, though...

[nrc]

See also rust-lang/rfcs#1561, which has a bunch of discussion in the comment thread about whether ! is part of the macro name or usage.

[nrc]

@steveklabnik this is my only PR with a breaking change in it at the moment, I don't have anything else planned and I think the bustage here will be pretty minor. I do think we should be willing to eat some breakage in Rustdoc - the implementation needs some serious work and unfortunately what should be implementation details is exposed in public interfaces such as URLs, if we're forever shy of breaking, we'll be stuck with the current implementation. Agree it's good to have a strategy to minimise pain.

[ollie27]

Well if you do change the URLs, for this to pass linkchecker you'll need to add redirects and/or update all the manual links in the docs.

[steveklabnik]

Gonna add this to the doc team meeting agenda for this week

[nrc]

@steveklabnik let me know what you come up with - I can update the links in the docs, but not worth doing unless you'll take the patch

[steveklabnik]

@nrc We talked at the doc team, and we're 👍 on merging this patch. Please do!

[alexcrichton]

@bors: r+ b55a28317fcb1c5e175d2b1dcba1b6088a808231

May as well help to see the errors from the linkchecker!

[bors]

⌛ Testing commit b55a283 with merge 7097fe5...

[bors]

💔 Test failed - auto-win-gnu-32-opt-rustbuild

[insaneinside]

This will break any links to macros in user-crate documentation.
Does crater check for broken links? Hell, does rustdoc even check for broken links? I find it usually just renders the markdown as text instead of producing an error!

[nrc]

Crater does not. Rustdoc does not. There is a linkchecker tool which does.

This will be a breaking change for docs.

[ollie27]

We don't have to break anything if we just add redirects. IMO if we change URLs then we have to add redirects.

[steveklabnik]

Yes, we want to make sure the redirects are here.

[nrc]

Now with links fixed and redirects added (no longer a breaking change).

r? @steveklabnik

[ollie27]

Maybe add a test to make sure the redirects are generated correctly?

[nrc]

now with bonus test

[bors]

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

[nrc]

rebased

[nrc]

ping @steveklabnik r?

[steveklabnik]

@bor: r+ rollup

[ollie27]

@steveklabnik looks like you misspelt @bors

[alexcrichton]

@bors: r=steveklabnik rollup

[bors]

📌 Commit 301401e has been approved by steveklabnik