Rollup merge of rust-lang#70242 - DeeDeeG:improve-e0308, r=Dylan-DPC

Improve E0308 error message wording

Hi folks,

I made [a post on Reddit](https://old.reddit.com/r/rust/comments/fmi11x/consider_linting_rusts_documentationerror_text/) about how (IMO) the docs/error messages can be a bit intimidating, one thing led to another, and I was encouraged to submit a Pull Request if I felt I could re-phrase the error message that I used as an example.

So that's this Pull Request. Open to any feedback or style changes, and I understand this is subjective.

(On another note: I am happy to see [this message was recently improved](rust-lang#69139) in `master`, so it's already better than it is in stable Rust 1.42.0.)

Ideally the last sentence could be split into at least two: [sentence explaining the inferred type.] [Sentence explaining explicit type.] [Sentence that summarizes that "this is bad," and why.]

But I'm not sure how to do so; I'm wary of writing something that turns out to be technically incorrect.

src/librustc_error_codes/error_codes/E0308.md

@@ -13,7 +13,7 @@ let x: i32 = "I am not a number!";
 ```
 
 This error occurs when the compiler was unable to infer the concrete type of a
-variable. It can occur for several cases, the most common of which is a
-mismatch in the expected type that the compiler inferred for a variable's
-initializing expression, and the actual type explicitly assigned to the
-variable.
+variable. It can happen in several cases, the most common being a mismatch
+between the type that the compiler inferred for a variable based on its
+initializing expression, on the one hand, and the type the author explicitly
+assigned to the variable, on the other hand.

src/test/ui/json-bom-plus-crlf-multifile.stderr

@@ -13,10 +13,10 @@ let x: i32 = \"I am not a number!\";
 ```
 
 This error occurs when the compiler was unable to infer the concrete type of a
-variable. It can occur for several cases, the most common of which is a
-mismatch in the expected type that the compiler inferred for a variable's
-initializing expression, and the actual type explicitly assigned to the
-variable.
+variable. It can happen in several cases, the most common being a mismatch
+between the type that the compiler inferred for a variable based on its
+initializing expression, on the one hand, and the type the author explicitly
+assigned to the variable, on the other hand.
 "},"level":"error","spans":[{"file_name":"$DIR/json-bom-plus-crlf-multifile-aux.rs","byte_start":621,"byte_end":622,"line_start":17,"line_end":17,"column_start":22,"column_end":23,"is_primary":true,"text":[{"text":"    let s : String = 1;  // Error in the middle of line.","highlight_start":22,"highlight_end":23}],"label":"expected struct `std::string::String`, found integer","suggested_replacement":null,"suggestion_applicability":null,"expansion":null},{"file_name":"$DIR/json-bom-plus-crlf-multifile-aux.rs","byte_start":612,"byte_end":618,"line_start":17,"line_end":17,"column_start":13,"column_end":19,"is_primary":false,"text":[{"text":"    let s : String = 1;  // Error in the middle of line.","highlight_start":13,"highlight_end":19}],"label":"expected due to this","suggested_replacement":null,"suggestion_applicability":null,"expansion":null}],"children":[{"message":"try using a conversion method","code":null,"level":"help","spans":[{"file_name":"$DIR/json-bom-plus-crlf-multifile-aux.rs","byte_start":621,"byte_end":622,"line_start":17,"line_end":17,"column_start":22,"column_end":23,"is_primary":true,"text":[{"text":"    let s : String = 1;  // Error in the middle of line.","highlight_start":22,"highlight_end":23}],"label":null,"suggested_replacement":"1.to_string()","suggestion_applicability":"MaybeIncorrect","expansion":null}],"children":[],"rendered":null}],"rendered":"$DIR/json-bom-plus-crlf-multifile-aux.rs:17:22: error[E0308]: mismatched types
 "}
 {"message":"mismatched types","code":{"code":"E0308","explanation":"Expected type did not match the received type.
@@ -34,10 +34,10 @@ let x: i32 = \"I am not a number!\";
 ```
 
 This error occurs when the compiler was unable to infer the concrete type of a
-variable. It can occur for several cases, the most common of which is a
-mismatch in the expected type that the compiler inferred for a variable's
-initializing expression, and the actual type explicitly assigned to the
-variable.
+variable. It can happen in several cases, the most common being a mismatch
+between the type that the compiler inferred for a variable based on its
+initializing expression, on the one hand, and the type the author explicitly
+assigned to the variable, on the other hand.
 "},"level":"error","spans":[{"file_name":"$DIR/json-bom-plus-crlf-multifile-aux.rs","byte_start":681,"byte_end":682,"line_start":19,"line_end":19,"column_start":22,"column_end":23,"is_primary":true,"text":[{"text":"    let s : String = 1","highlight_start":22,"highlight_end":23}],"label":"expected struct `std::string::String`, found integer","suggested_replacement":null,"suggestion_applicability":null,"expansion":null},{"file_name":"$DIR/json-bom-plus-crlf-multifile-aux.rs","byte_start":672,"byte_end":678,"line_start":19,"line_end":19,"column_start":13,"column_end":19,"is_primary":false,"text":[{"text":"    let s : String = 1","highlight_start":13,"highlight_end":19}],"label":"expected due to this","suggested_replacement":null,"suggestion_applicability":null,"expansion":null}],"children":[{"message":"try using a conversion method","code":null,"level":"help","spans":[{"file_name":"$DIR/json-bom-plus-crlf-multifile-aux.rs","byte_start":681,"byte_end":682,"line_start":19,"line_end":19,"column_start":22,"column_end":23,"is_primary":true,"text":[{"text":"    let s : String = 1","highlight_start":22,"highlight_end":23}],"label":null,"suggested_replacement":"1.to_string()","suggestion_applicability":"MaybeIncorrect","expansion":null}],"children":[],"rendered":null}],"rendered":"$DIR/json-bom-plus-crlf-multifile-aux.rs:19:22: error[E0308]: mismatched types
 "}
 {"message":"mismatched types","code":{"code":"E0308","explanation":"Expected type did not match the received type.
@@ -55,10 +55,10 @@ let x: i32 = \"I am not a number!\";
 ```
 
 This error occurs when the compiler was unable to infer the concrete type of a
-variable. It can occur for several cases, the most common of which is a
-mismatch in the expected type that the compiler inferred for a variable's
-initializing expression, and the actual type explicitly assigned to the
-variable.
+variable. It can happen in several cases, the most common being a mismatch
+between the type that the compiler inferred for a variable based on its
+initializing expression, on the one hand, and the type the author explicitly
+assigned to the variable, on the other hand.
 "},"level":"error","spans":[{"file_name":"$DIR/json-bom-plus-crlf-multifile-aux.rs","byte_start":745,"byte_end":746,"line_start":23,"line_end":23,"column_start":1,"column_end":2,"is_primary":true,"text":[{"text":"1;  // Error after the newline.","highlight_start":1,"highlight_end":2}],"label":"expected struct `std::string::String`, found integer","suggested_replacement":null,"suggestion_applicability":null,"expansion":null},{"file_name":"$DIR/json-bom-plus-crlf-multifile-aux.rs","byte_start":735,"byte_end":741,"line_start":22,"line_end":22,"column_start":13,"column_end":19,"is_primary":false,"text":[{"text":"    let s : String =","highlight_start":13,"highlight_end":19}],"label":"expected due to this","suggested_replacement":null,"suggestion_applicability":null,"expansion":null}],"children":[{"message":"try using a conversion method","code":null,"level":"help","spans":[{"file_name":"$DIR/json-bom-plus-crlf-multifile-aux.rs","byte_start":745,"byte_end":746,"line_start":23,"line_end":23,"column_start":1,"column_end":2,"is_primary":true,"text":[{"text":"1;  // Error after the newline.","highlight_start":1,"highlight_end":2}],"label":null,"suggested_replacement":"1.to_string()","suggestion_applicability":"MaybeIncorrect","expansion":null}],"children":[],"rendered":null}],"rendered":"$DIR/json-bom-plus-crlf-multifile-aux.rs:23:1: error[E0308]: mismatched types
 "}
 {"message":"mismatched types","code":{"code":"E0308","explanation":"Expected type did not match the received type.
@@ -76,10 +76,10 @@ let x: i32 = \"I am not a number!\";
 ```
 
 This error occurs when the compiler was unable to infer the concrete type of a
-variable. It can occur for several cases, the most common of which is a
-mismatch in the expected type that the compiler inferred for a variable's
-initializing expression, and the actual type explicitly assigned to the
-variable.
+variable. It can happen in several cases, the most common being a mismatch
+between the type that the compiler inferred for a variable based on its
+initializing expression, on the one hand, and the type the author explicitly
+assigned to the variable, on the other hand.
 "},"level":"error","spans":[{"file_name":"$DIR/json-bom-plus-crlf-multifile-aux.rs","byte_start":801,"byte_end":809,"line_start":25,"line_end":26,"column_start":22,"column_end":6,"is_primary":true,"text":[{"text":"    let s : String = (","highlight_start":22,"highlight_end":23},{"text":"    );  // Error spanning the newline.","highlight_start":1,"highlight_end":6}],"label":"expected struct `std::string::String`, found `()`","suggested_replacement":null,"suggestion_applicability":null,"expansion":null},{"file_name":"$DIR/json-bom-plus-crlf-multifile-aux.rs","byte_start":792,"byte_end":798,"line_start":25,"line_end":25,"column_start":13,"column_end":19,"is_primary":false,"text":[{"text":"    let s : String = (","highlight_start":13,"highlight_end":19}],"label":"expected due to this","suggested_replacement":null,"suggestion_applicability":null,"expansion":null}],"children":[],"rendered":"$DIR/json-bom-plus-crlf-multifile-aux.rs:25:22: error[E0308]: mismatched types
 "}
 {"message":"aborting due to 4 previous errors","code":null,"level":"error","spans":[],"children":[],"rendered":"error: aborting due to 4 previous errors

src/test/ui/json-bom-plus-crlf.stderr

@@ -13,10 +13,10 @@ let x: i32 = \"I am not a number!\";
 ```
 
 This error occurs when the compiler was unable to infer the concrete type of a
-variable. It can occur for several cases, the most common of which is a
-mismatch in the expected type that the compiler inferred for a variable's
-initializing expression, and the actual type explicitly assigned to the
-variable.
+variable. It can happen in several cases, the most common being a mismatch
+between the type that the compiler inferred for a variable based on its
+initializing expression, on the one hand, and the type the author explicitly
+assigned to the variable, on the other hand.
 "},"level":"error","spans":[{"file_name":"$DIR/json-bom-plus-crlf.rs","byte_start":606,"byte_end":607,"line_start":16,"line_end":16,"column_start":22,"column_end":23,"is_primary":true,"text":[{"text":"    let s : String = 1;  // Error in the middle of line.","highlight_start":22,"highlight_end":23}],"label":"expected struct `std::string::String`, found integer","suggested_replacement":null,"suggestion_applicability":null,"expansion":null},{"file_name":"$DIR/json-bom-plus-crlf.rs","byte_start":597,"byte_end":603,"line_start":16,"line_end":16,"column_start":13,"column_end":19,"is_primary":false,"text":[{"text":"    let s : String = 1;  // Error in the middle of line.","highlight_start":13,"highlight_end":19}],"label":"expected due to this","suggested_replacement":null,"suggestion_applicability":null,"expansion":null}],"children":[{"message":"try using a conversion method","code":null,"level":"help","spans":[{"file_name":"$DIR/json-bom-plus-crlf.rs","byte_start":606,"byte_end":607,"line_start":16,"line_end":16,"column_start":22,"column_end":23,"is_primary":true,"text":[{"text":"    let s : String = 1;  // Error in the middle of line.","highlight_start":22,"highlight_end":23}],"label":null,"suggested_replacement":"1.to_string()","suggestion_applicability":"MaybeIncorrect","expansion":null}],"children":[],"rendered":null}],"rendered":"$DIR/json-bom-plus-crlf.rs:16:22: error[E0308]: mismatched types
 "}
 {"message":"mismatched types","code":{"code":"E0308","explanation":"Expected type did not match the received type.
@@ -34,10 +34,10 @@ let x: i32 = \"I am not a number!\";
 ```
 
 This error occurs when the compiler was unable to infer the concrete type of a
-variable. It can occur for several cases, the most common of which is a
-mismatch in the expected type that the compiler inferred for a variable's
-initializing expression, and the actual type explicitly assigned to the
-variable.
+variable. It can happen in several cases, the most common being a mismatch
+between the type that the compiler inferred for a variable based on its
+initializing expression, on the one hand, and the type the author explicitly
+assigned to the variable, on the other hand.
 "},"level":"error","spans":[{"file_name":"$DIR/json-bom-plus-crlf.rs","byte_start":666,"byte_end":667,"line_start":18,"line_end":18,"column_start":22,"column_end":23,"is_primary":true,"text":[{"text":"    let s : String = 1","highlight_start":22,"highlight_end":23}],"label":"expected struct `std::string::String`, found integer","suggested_replacement":null,"suggestion_applicability":null,"expansion":null},{"file_name":"$DIR/json-bom-plus-crlf.rs","byte_start":657,"byte_end":663,"line_start":18,"line_end":18,"column_start":13,"column_end":19,"is_primary":false,"text":[{"text":"    let s : String = 1","highlight_start":13,"highlight_end":19}],"label":"expected due to this","suggested_replacement":null,"suggestion_applicability":null,"expansion":null}],"children":[{"message":"try using a conversion method","code":null,"level":"help","spans":[{"file_name":"$DIR/json-bom-plus-crlf.rs","byte_start":666,"byte_end":667,"line_start":18,"line_end":18,"column_start":22,"column_end":23,"is_primary":true,"text":[{"text":"    let s : String = 1","highlight_start":22,"highlight_end":23}],"label":null,"suggested_replacement":"1.to_string()","suggestion_applicability":"MaybeIncorrect","expansion":null}],"children":[],"rendered":null}],"rendered":"$DIR/json-bom-plus-crlf.rs:18:22: error[E0308]: mismatched types
 "}
 {"message":"mismatched types","code":{"code":"E0308","explanation":"Expected type did not match the received type.
@@ -55,10 +55,10 @@ let x: i32 = \"I am not a number!\";
 ```
 
 This error occurs when the compiler was unable to infer the concrete type of a
-variable. It can occur for several cases, the most common of which is a
-mismatch in the expected type that the compiler inferred for a variable's
-initializing expression, and the actual type explicitly assigned to the
-variable.
+variable. It can happen in several cases, the most common being a mismatch
+between the type that the compiler inferred for a variable based on its
+initializing expression, on the one hand, and the type the author explicitly
+assigned to the variable, on the other hand.
 "},"level":"error","spans":[{"file_name":"$DIR/json-bom-plus-crlf.rs","byte_start":730,"byte_end":731,"line_start":22,"line_end":22,"column_start":1,"column_end":2,"is_primary":true,"text":[{"text":"1;  // Error after the newline.","highlight_start":1,"highlight_end":2}],"label":"expected struct `std::string::String`, found integer","suggested_replacement":null,"suggestion_applicability":null,"expansion":null},{"file_name":"$DIR/json-bom-plus-crlf.rs","byte_start":720,"byte_end":726,"line_start":21,"line_end":21,"column_start":13,"column_end":19,"is_primary":false,"text":[{"text":"    let s : String =","highlight_start":13,"highlight_end":19}],"label":"expected due to this","suggested_replacement":null,"suggestion_applicability":null,"expansion":null}],"children":[{"message":"try using a conversion method","code":null,"level":"help","spans":[{"file_name":"$DIR/json-bom-plus-crlf.rs","byte_start":730,"byte_end":731,"line_start":22,"line_end":22,"column_start":1,"column_end":2,"is_primary":true,"text":[{"text":"1;  // Error after the newline.","highlight_start":1,"highlight_end":2}],"label":null,"suggested_replacement":"1.to_string()","suggestion_applicability":"MaybeIncorrect","expansion":null}],"children":[],"rendered":null}],"rendered":"$DIR/json-bom-plus-crlf.rs:22:1: error[E0308]: mismatched types
 "}
 {"message":"mismatched types","code":{"code":"E0308","explanation":"Expected type did not match the received type.
@@ -76,10 +76,10 @@ let x: i32 = \"I am not a number!\";
 ```
 
 This error occurs when the compiler was unable to infer the concrete type of a
-variable. It can occur for several cases, the most common of which is a
-mismatch in the expected type that the compiler inferred for a variable's
-initializing expression, and the actual type explicitly assigned to the
-variable.
+variable. It can happen in several cases, the most common being a mismatch
+between the type that the compiler inferred for a variable based on its
+initializing expression, on the one hand, and the type the author explicitly
+assigned to the variable, on the other hand.
 "},"level":"error","spans":[{"file_name":"$DIR/json-bom-plus-crlf.rs","byte_start":786,"byte_end":794,"line_start":24,"line_end":25,"column_start":22,"column_end":6,"is_primary":true,"text":[{"text":"    let s : String = (","highlight_start":22,"highlight_end":23},{"text":"    );  // Error spanning the newline.","highlight_start":1,"highlight_end":6}],"label":"expected struct `std::string::String`, found `()`","suggested_replacement":null,"suggestion_applicability":null,"expansion":null},{"file_name":"$DIR/json-bom-plus-crlf.rs","byte_start":777,"byte_end":783,"line_start":24,"line_end":24,"column_start":13,"column_end":19,"is_primary":false,"text":[{"text":"    let s : String = (","highlight_start":13,"highlight_end":19}],"label":"expected due to this","suggested_replacement":null,"suggestion_applicability":null,"expansion":null}],"children":[],"rendered":"$DIR/json-bom-plus-crlf.rs:24:22: error[E0308]: mismatched types
 "}
 {"message":"aborting due to 4 previous errors","code":null,"level":"error","spans":[],"children":[],"rendered":"error: aborting due to 4 previous errors