Improve codegen option docs.

This commit:
- Adds "following values" indicators for all the options that are
  missing them.
- Tweaks some wording and punctuation for consistency.
- Rewords some things for clarity.
- Removes the `no-integrated-as` entry, because that option was removed
  in #70345.

1 files changed, 101 insertions, 84 deletions

diff --git a/src/doc/rustc/src/codegen-options/index.md b/src/doc/rustc/src/codegen-options/index.md
index 8dc6257ce2e..22cdc9f2339 100644
--- a/src/doc/rustc/src/codegen-options/index.md
+++ b/src/doc/rustc/src/codegen-options/index.md
@@ -9,10 +9,10 @@ This option is deprecated and does nothing.
 
 ## linker
 
-This flag lets you control which linker `rustc` invokes to link your code. It
-takes a path to the linker executable. If this flag is not specified, the
-linker will be inferred based on the target. See also the
-[linker-flavor](#linker-flavor) flag for another way to specify the linker.
+This flag controls which linker `rustc` invokes to link your code. It takes a
+path to the linker executable. If this flag is not specified, the linker will
+be inferred based on the target. See also the [linker-flavor](#linker-flavor)
+flag for another way to specify the linker.
 
 ## link-arg
 
@@ -27,49 +27,52 @@ options should be separated by spaces.
 
 ## linker-flavor
 
-This flag lets you control the linker flavor used by `rustc`. If a linker is given with the
-[`-C linker` flag](#linker), then the linker flavor is inferred from the value provided. If no
-linker is given then the linker flavor is used to determine the linker to use. Every `rustc` target
-defaults to some linker flavor. Valid options are:
-
-* `em`: Uses [Emscripten `emcc`](https://emscripten.org/docs/tools_reference/emcc.html).
-* `gcc`: Uses the `cc` executable, which is typically gcc or clang on many systems.
-* `ld`: Uses the `ld` executable.
-* `msvc`: Uses the `link.exe` executable from Microsoft Visual Studio MSVC.
-* `ptx-linker`: Uses
+This flag controls the linker flavor used by `rustc`. If a linker is given with
+the [`-C linker` flag](#linker), then the linker flavor is inferred from the
+value provided. If no linker is given then the linker flavor is used to
+determine the linker to use. Every `rustc` target defaults to some linker
+flavor. Valid options are:
+
+* `em`: use [Emscripten `emcc`](https://emscripten.org/docs/tools_reference/emcc.html).
+* `gcc`: use the `cc` executable, which is typically gcc or clang on many systems.
+* `ld`: use the `ld` executable.
+* `msvc`: use the `link.exe` executable from Microsoft Visual Studio MSVC.
+* `ptx-linker`: use
   [`rust-ptx-linker`](https://github.com/denzp/rust-ptx-linker) for Nvidia
   NVPTX GPGPU support.
-* `wasm-ld`: Uses the [`wasm-ld`](https://lld.llvm.org/WebAssembly.html)
+* `wasm-ld`: use the [`wasm-ld`](https://lld.llvm.org/WebAssembly.html)
   executable, a port of LLVM `lld` for WebAssembly.
-* `ld64.lld`: Uses the LLVM `lld` executable with the [`-flavor darwin`
+* `ld64.lld`: use the LLVM `lld` executable with the [`-flavor darwin`
   flag][lld-flavor] for Apple's `ld`.
-* `ld.lld`: Uses the LLVM `lld` executable with the [`-flavor gnu`
+* `ld.lld`: use the LLVM `lld` executable with the [`-flavor gnu`
   flag][lld-flavor] for GNU binutils' `ld`.
-* `lld-link`: Uses the LLVM `lld` executable with the [`-flavor link`
+* `lld-link`: use the LLVM `lld` executable with the [`-flavor link`
   flag][lld-flavor] for Microsoft's `link.exe`.
 
 [lld-flavor]: https://lld.llvm.org/Driver.html
 
 ## link-dead-code
 
-Normally, the linker will remove dead code. This flag disables this behavior.
+This flag controls whether the linker will keep dead code. It takes one of
+the following values:
+
+* `y`, `yes`, `on`, or no value: keep dead code.
+* `n`, `no`, or `off`: remove dead code (the default).
 
 An example of when this flag might be useful is when trying to construct code coverage
 metrics.
 
 ## lto
 
-This flag instructs LLVM to use [link time
+This flag controls whether LLVM uses [link time
 optimizations](https://llvm.org/docs/LinkTimeOptimization.html) to produce
 better optimized code, using whole-program analysis, at the cost of longer
-linking time.
-
-This flag may take one of the following values:
+linking time. It takes one of the following values:
 
-* `y`, `yes`, `on`, `fat`, or no value: Performs "fat" LTO which attempts to
+* `y`, `yes`, `on`, `fat`, or no value: perform "fat" LTO which attempts to
   perform optimizations across all crates within the dependency graph.
-* `n`, `no`, `off`: Disables LTO.
-* `thin`: Performs ["thin"
+* `n`, `no`, `off`: disables LTO.
+* `thin`: perform ["thin"
   LTO](http://blog.llvm.org/2016/06/thinlto-scalable-and-incremental-lto.html).
   This is similar to "fat", but takes substantially less time to run while
   still achieving performance gains similar to "fat".
@@ -81,22 +84,22 @@ disabled if codegen units is 1 or optimizations are disabled ([`-C
 opt-level=0`](#opt-level)). That is:
 
 * When `-C lto` is not specified:
-  * `codegen-units=1`: Disables LTO.
-  * `opt-level=0`: Disables LTO.
+  * `codegen-units=1`: disable LTO.
+  * `opt-level=0`: disable LTO.
 * When `-C lto=true`:
-  * `lto=true`: 16 codegen units, performs fat LTO across crates.
+  * `lto=true`: 16 codegen units, perform fat LTO across crates.
   * `codegen-units=1` + `lto=true`: 1 codegen unit, fat LTO across crates.
 
 See also [linker-plugin-lto](#linker-plugin-lto) for cross-language LTO.
 
 ## linker-plugin-lto
 
-Defers LTO optimizations to the linker. See
-[linkger-plugin-LTO](../linker-plugin-lto.md) for more details. Takes one of
+This flag defers LTO optimizations to the linker. See
+[linker-plugin-LTO](../linker-plugin-lto.md) for more details. It takes one of
 the following values:
 
-* `y`, `yes`, `on`, or no value: Enabled.
-* `n`, `no`, or `off`: Disabled (default).
+* `y`, `yes`, `on`, or no value: enable linker plugin LTO.
+* `n`, `no`, or `off`: disable linker plugin LTO (the default).
 * A path to the linker plugin.
 
 ## target-cpu
@@ -148,14 +151,19 @@ Pass `--help` to see a list of options.
 
 ## save-temps
 
-`rustc` will generate temporary files during compilation; normally it will
-delete them after it's done with its work. This option will cause them to be
-preserved instead of removed.
+This flag controls whether temporary files generated during compilation are
+deleted once compilation finishes. It takes one of the following values:
+
+* `y`, `yes`, `on`, or no value: save temporary files.
+* `n`, `no`, or `off`: delete temporary files (the default).
 
 ## rpath
 
-This option allows you to enable
-[`rpath`](https://en.wikipedia.org/wiki/Rpath).
+This flag controls whether [`rpath`](https://en.wikipedia.org/wiki/Rpath) is
+enabled. It takes one of the following values:
+
+* `y`, `yes`, `on`, or no value: enable rpath.
+* `n`, `no`, or `off`: disable rpath (the default).
 
 ## overflow-checks
 
@@ -164,35 +172,46 @@ overflow](../../reference/expressions/operator-expr.md#overflow). When
 overflow-checks are enabled, a panic will occur on overflow. This flag takes
 one of the following values:
 
-* `y`, `yes`, `on`, or no value: Enable overflow checks.
-* `n`, `no`, or `off`: Disable overflow checks.
+* `y`, `yes`, `on`, or no value: enable overflow checks.
+* `n`, `no`, or `off`: disable overflow checks.
 
 If not specified, overflow checks are enabled if
 [debug-assertions](#debug-assertions) are enabled, disabled otherwise.
 
 ## no-prepopulate-passes
 
-The pass manager comes pre-populated with a list of passes; this flag
-ensures that list is empty.
+This flag controls whether the pass manager uses a pre-populated list of
+passes. It takes one of the following values:
+
+* `y`, `yes`, `on`, or no value: use an empty list of passes.
+* `n`, `no`, or `off`: use a pre-populated list of passes (the default).
 
 ## no-vectorize-loops
 
-By default, `rustc` will attempt to [vectorize
-loops](https://llvm.org/docs/Vectorizers.html#the-loop-vectorizer). This
-flag will turn that behavior off.
+This flag controls whether `rustc` will attempt to [vectorize
+loops](https://llvm.org/docs/Vectorizers.html#the-loop-vectorizer). It takes
+one of the following values:
+
+* `y`, `yes`, `on`, or no value: disable loop vectorization.
+* `n`, `no`, or `off`: enable loop vectorization (the default).
 
 ## no-vectorize-slp
 
-By default, `rustc` will attempt to vectorize code using [superword-level
-parallelism](https://llvm.org/docs/Vectorizers.html#the-slp-vectorizer). This
-flag will turn that behavior off.
+This flag controls whether `rustc` will attempt to vectorize code using
+[superword-level
+parallelism](https://llvm.org/docs/Vectorizers.html#the-slp-vectorizer).
+It takes one of the following values:
+
+* `y`, `yes`, `on`, or no value: disable SLP vectorization.
+* `n`, `no`, or `off`: enable SLP vectorization (the default).
 
 ## soft-float
 
-This option will make `rustc` generate code using "soft floats." By default,
-a lot of hardware supports floating point instructions, and so the code generated
-will take advantage of this. "soft floats" emulate floating point instructions
-in software.
+This option controls whether `rustc` generates code that emulates floating
+point instructions in software. It takes one of the following values:
+
+* `y`, `yes`, `on`, or no value: use soft floats.
+* `n`, `no`, or `off`: use hardware floats (the default).
 
 ## prefer-dynamic
 
@@ -201,24 +220,21 @@ indicate that dynamic linking should be used if possible if both a static and
 dynamic versions of a library are available. There is an internal algorithm
 for determining whether or not it is possible to statically or dynamically
 link with a dependency. For example, `cdylib` crate types may only use static
-linkage.
-
-## no-integrated-as
+linkage. This flag takes one of the following values:
 
-`rustc` normally uses the LLVM internal assembler to create object code. This
-flag will disable the internal assembler and emit assembly code to be
-translated using an external assembler, currently the linker such as `cc`.
+* `y`, `yes`, `on`, or no value: use dynamic linking.
+* `n`, `no`, or `off`: use static linking (the default).
 
 ## no-redzone
 
 This flag allows you to disable [the
-red zone](https://en.wikipedia.org/wiki/Red_zone_\(computing\)). This flag can
-be passed one of the following options:
+red zone](https://en.wikipedia.org/wiki/Red_zone_\(computing\)). It takes one
+of the following values:
 
-* `y`, `yes`, `on`, or no value: Disables the red zone.
-* `n`, `no`, or `off`: Enables the red zone.
+* `y`, `yes`, `on`, or no value: disable the red zone.
+* `n`, `no`, or `off`: enable the red zone.
 
-The default if not specified depends on the target.
+The default behaviour, if the flag is not specified, depends on the target.
 
 ## relocation-model
 
@@ -257,7 +273,7 @@ them in parallel. Increasing parallelism may speed up compile times, but may
 also produce slower code. Setting this to 1 may improve the performance of
 generated code, but may be slower to compile.
 
-The default, if not specified, is 16 for non-incremental builds. For
+The default value, if not specified, is 16 for non-incremental builds. For
 incremental builds the default is 256 which allows caching to be more granular.
 
 ## remark
@@ -274,24 +290,26 @@ This option is deprecated and does nothing.
 
 ## debuginfo
 
-This flag lets you control debug information:
+This flag controls the generation of debug information. It takes one of the
+following values:
 
-* `0`: no debug info at all (default)
-* `1`: line tables only
-* `2`: full debug info
+* `0`: no debug info at all (the default).
+* `1`: line tables only.
+* `2`: full debug info.
 
 Note: The [`-g` flag][option-g-debug] is an alias for `-C debuginfo=2`.
 
 ## opt-level
 
-This flag lets you control the optimization level.
+This flag controls the optimization level.
 
-* `0`: no optimizations, also turns on [`cfg(debug_assertions)`](#debug-assertions).
-* `1`: basic optimizations
-* `2`: some optimizations
-* `3`: all optimizations
-* `s`: optimize for binary size
-* `z`: optimize for binary size, but also turn off loop vectorization.
+* `0`: no optimizations, also turns on
+  [`cfg(debug_assertions)`](#debug-assertions) (the default).
+* `1`: basic optimizations.
+* `2`: some optimizations.
+* `3`: all optimizations.
+* `s`: optimize for binary size.
+* `z`: optimize for binary size, but also turn off loop vectorization..
 
 Note: The [`-O` flag][option-o-optimize] is an alias for `-C opt-level=2`.
 
@@ -303,8 +321,8 @@ This flag lets you turn `cfg(debug_assertions)` [conditional
 compilation](../../reference/conditional-compilation.md#debug_assertions) on
 or off. It takes one of the following values:
 
-* `y`, `yes`, `on`, or no value: Enable debug-assertions.
-* `n`, `no`, or `off`: Disable debug-assertions.
+* `y`, `yes`, `on`, or no value: enable debug-assertions.
+* `n`, `no`, or `off`: disable debug-assertions.
 
 If not specified, debug assertions are automatically enabled only if the
 [opt-level](#opt-level) is 0.
@@ -362,25 +380,24 @@ to a valid `.profdata` file. See the chapter on
 This flag forces the use of frame pointers. It takes one of the following
 values:
 
-* `y`, `yes`, `on`, or no value: Frame pointers are forced to be enabled.
-* `n`, `no`, or `off`: Frame pointers are not forced to be enabled. This does
+* `y`, `yes`, `on`, or no value: force-enable frame pointers.
+* `n`, `no`, or `off`: do not force-enable frame pointers. This does
   not necessarily mean frame pointers will be removed.
 
-The default if not specified depends on the target.
+The default behaviour, if frame pointers are not force-enabled, depends on the
+target.
 
 ## default-linker-libraries
 
 This flag controls whether or not the linker includes its default libraries.
 It takes one of the following values:
 
-* `y`, `yes`, `on`, or no value: Default libraries are included.
-* `n`, `no`, or `off`: Default libraries are **not** included.
+* `y`, `yes`, `on`, or no value: include default libraries (the default).
+* `n`, `no`, or `off`: exclude default libraries.
 
 For example, for gcc flavor linkers, this issues the `-nodefaultlibs` flag to
 the linker.
 
-The default is `yes` if not specified.
-
 [option-emit]: ../command-line-arguments.md#option-emit
 [option-o-optimize]: ../command-line-arguments.md#option-o-optimize
 [profile-guided optimization]: ../profile-guided-optimization.md