Fix confusing compiler diagnostic messages and error code docs

[axeroofficialtournament-del]

This PR fixes a bunch of long standing issues in rust’s error messages. Many were baffling or even misleading or simply didn't tell me what the real problem was. I have been waiting to clean a while and there were a lot of open issues around these.
What I changed to improve personally.

Slightly better wording of error messages:
The old “escapes the closure body” message is never clear:
E0521. I changed the explanation to actually say what “escapes” means (the reference outlives the scope it was borrowed in). Also I indicated that it is not a style suggestion, but actually a mistake and corrected the problematic “Consider to drop it” grammar.
E0603 : Sometimes we were emitting “unit variant is private”, which is wrong enum variants are not private! I made a comment about the false positive, and directed the user to the correct error (E0638).
E0638 : updated the documentation so that the rules it must follow are explained and includes concrete match examples on what breaks and fixes the document. I also created a cross link to E0603.
The case for the nested loop is a completely different from the simple move error one and was hidden within the same docs – The nested loop case is (this reinitialization might get skipped). I dedicated a section for it so it's not mixed in with the other sections, and included the continue 'outer fix and clone/borrow alternatives.
For E0038, I finally put an explanation at the very top of this, because many of the questions are confusing because of lack of understanding of what an “object” is. I also included a note about the common error of using Into as a parameter type, rather than impl Into.
E0308 : I've added special cases for two common beginner traps: function argument mismatch and the semicolon traps expression into the parentheses. The latter is something nearly everyone new to the language doesn't understand what it is.
E0277 : From not implemented — No mention of the ? operator. I included a section of explaining the implicit conversion, what ? expands to, and 3 ways to remedy it.
E0283: This is a common error where the people are trying to call .into::() on y, with no helpful error message. I added a section to the reasons why turbofish doesn't work with trait methods and how it should be done.

Fixed contradictory terminology:
E0658 / parser : The old “let expressions are not supported here” message is in contradiction with the Book which rightfully refers to “let a statement”. A note was added to E0658 to remind people about the difference between statement and expression (which had already been used by the parser in the new diagnostic).
Avoid the actual syntax error by getting the doc comment diagnostic instead of “this doc comment doesn’t document anything”. I added a note to explain that a syntax error in the next item can cause this warning, so that users will know to scroll down.

Filled documentation gaps:
E0117 : Orphan rule was explained, but people were not helped to recognise the three cases where the rule applies. I've included the explainer of “local vs foreign” with runnable examples for both cases, along with the common fix of the “newtype” pattern.
There was no .md file at all found in the directory with this error code: E0035 I wrote one to explain why turbofish does not work with trait methods, and what to do about that. I also cross linked it from E0283.

Better ICE messages:
session_diagnostics : Panic by the compiler did not provide any clue for the user on what to do next. To the basic, I added helpful notes to direct people to set RUST_BACKTRACE=1, cargo clean and report a bug; all of these things people need to know, but they have to google.

[rustbot]

The parser was modified, potentially altering the grammar of (stable) Rust
which would be a breaking change.

cc @fmease

[rustbot]

Thanks for the pull request, and welcome! The Rust Project is excited to review your changes, and you should hear from @mati865 (or someone else) some time within the next two weeks.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

• @rustbot author: the review is finished, PR author should check the comments and take action accordingly
• @rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: compiler
• compiler expanded to 75 candidates
• Random selection from 21 candidates

[rustbot]

⚠️ Warning ⚠️

• There are issue links (such as #123) in the commit messages of the following commits.
  Please move them to the PR description, to avoid spamming the issues with references to the commit, and so this bot can automatically canonicalize them to avoid issues with subtree.
  • 8f370d1

[rust-log-analyzer]

The job tidy failed! Check out the build log: (web) (plain enhanced) (plain)

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

[TIMING:end] tool::ToolBuild { build_compiler: Compiler { stage: 0, host: x86_64-unknown-linux-gnu, forced_compiler: false }, target: x86_64-unknown-linux-gnu, tool: "tidy", path: "src/tools/tidy", mode: ToolBootstrap, source_type: InTree, extra_features: [], allow_features: "", cargo_args: [], artifact_kind: Binary } -- 10.946
[TIMING:end] tool::Tidy { compiler: Compiler { stage: 0, host: x86_64-unknown-linux-gnu, forced_compiler: false }, target: x86_64-unknown-linux-gnu } -- 0.000
fmt check
Diff in /checkout/compiler/rustc_parse/src/diagnostics.rs:1332:
 #[derive(Diagnostic)]
 #[diag("found a documentation comment that doesn't document anything", code = E0585)]
 #[help("doc comments must come before what they document, if a comment was intended use `//`")]
-#[note("if the following item has a syntax error, fix that first — a syntax error can cause this warning to appear even when the doc comment placement is correct")]
+#[note(
+    "if the following item has a syntax error, fix that first — a syntax error can cause this warning to appear even when the doc comment placement is correct"
+)]
 pub(crate) struct DocCommentDoesNotDocumentAnything {
     #[primary_span]
     pub span: Span,
fmt: checked 7020 files
Bootstrap failed while executing `test src/tools/tidy tidyselftest --extra-checks=py,cpp,js,spellcheck`
Currently active steps:
test::Tidy {  } at src/bootstrap/src/core/build_steps/test.rs:1566
Build completed unsuccessfully in 0:00:48

[workingjubilee]

This PR fixes a bunch of long standing issues

Thank you for your PR, please separate the error code submissions from the other two changes.

View changes since this review

[workingjubilee]

We want to know when incremental errors are repeatedly recurring, and this feels like it tacitly encourages people to not report them. We could say something but I'm not sure it is this sort of "don't worry about it" thing?

[workingjubilee]

We do not require a minimal reproduction. We need any reproducer. And the link itself contains explanation of what we are hoping for in an ideal bug report.

[workingjubilee]

The "URL below" is on a line that says:

note: we would appreciate a bug report: https://github.com/rust-lang/rust/issues/new?labels=C-bug%2C+I-ICE%2C+T-compiler&template=ice.md

So this is not really new information?

View changes since the review

[mati865]

r? workingjubilee since they already did partial review? feel free to reroll

[rustbot]

workingjubilee is currently at their maximum review capacity.
They may take a while to respond.

[mati865]

Also CI is failing. @rustbot author

[rustbot]

Reminder, once the PR becomes ready for a review, use @rustbot ready.

[workingjubilee]

The new --explain submissions are probably something we can just decide to r+ or not, with only a review for correctness. I only have strong opinions on the things that relate to triage of stuff.

[rust-bors]

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