Provide a better error when code is put outside of a function

[meithecatte]

Examples in the documentation often provide excerpts instead of full programs. A beginner might try compiling that code directly, and be confused that it doesn't work. Currently, the error messages for that case don't provide any hints as to what might be wrong:

error: expected item, found keyword `let`
 --> src/lib.rs:1:1
  |
1 | let data = [4, 8, 15, 16, 23, 42];
  | ^^^ expected item

error: expected one of `!` or `::`, found `(`
 --> src/lib.rs:2:10
  |
2 | fs::write("foo.txt", "Hello!").unwrap();
  |          ^ expected one of `!` or `::`

error: macro expansion ignores token `{` and any following
   |
  ::: src/lib.rs:1:1
   |
1  |   println!("Hello, world!");
   |   ------------------------- caused by the macro expansion here
   |
   = note: the usage of `println!` is likely invalid in item context

Ideally the output should look like:

error: `let` is invalid outside of a function
 --> src/lib.rs:1:1
  |
1 | let data = [4, 8, 15, 16, 23, 42];
  | ^^^ not valid outside of a function
help: put your code in a `main` function:
  | fn main() {
  |     let data = [4, 8, 15, 16, 23, 42];
  |     for n in data {
  |         dbg!(n);
  |     }
  | }

[chordtoll]

@rustbot claim

[chordtoll]

After investigating, it looks like this functionality might not be possible without significant changes- the above errors occur in the parse stage, before we have the information needed to decide if other functions exist, or if the user did in fact make the mistake of trying to directly run a snippet.

[chordtoll]

I'm going to release this ticket so a contributor with more experience in the parser can hopefully give it a look

[chordtoll]

@rustbot release-assignment