Auto merge of #8953 - hkennyv:clarify-package-edition-docs, r=Eh2406

Clarify cargo manifest edition field docs

addresses #8951

This PR aims to clarify the documentation for the `edition` field in the Cargo manifest.

The confusion (IME) stems from the behavior of `cargo new` (defaults to writing edition = "2018") being confused for the default behavior of how Cargo interprets the manifest (`edition` is an optional key, defaults to 2015).

would love to get some other thoughts on how we can clarify this since it seems like I'm not the only one who got confused `@Eh2406`

Author: bors

src/doc/src/reference/manifest.md

@@ -118,22 +118,21 @@ brackets at the end of each author.
 <a id="the-edition-field-optional"></a>
 #### The `edition` field
 
-You can opt in to a specific [Rust Edition] for your package with the
-`edition` key in `Cargo.toml`. If you don't specify the edition, it will
-default to 2015.
+The `edition` key is an optional key that affects which edition your package
+is compiled with. [`cargo new`] will generate a package with the `edition` key
+set to the latest edition. Setting the `edition` key in
+`[package]` will affect all targets/crates in the package, including test
+suites, benchmarks, binaries, examples, etc.
+
+If the `edition` key is not set to a specific [Rust Edition] in your
+`Cargo.toml`, Cargo will default to 2015.
 
 ```toml
 [package]
 # ...
 edition = '2018'
 ```
 
-The `edition` key affects which edition your package is compiled with. Cargo
-will always generate packages via [`cargo new`] with the `edition` key set to the
-latest edition. Setting the `edition` key in `[package]` will affect all
-targets/crates in the package, including test suites, benchmarks, binaries,
-examples, etc.
-
 #### The `description` field
 
 The description is a short blurb about the package. [crates.io] will display