Rollup merge of #61389 - Zoxc:arena-cleanup, r=eddyb

[rust.git] / src / doc / rustdoc / src / command-line-arguments.md

diff --git a/src/doc/rustdoc/src/command-line-arguments.md b/src/doc/rustdoc/src/command-line-arguments.md
index bf72a489b5a2870c943fb78841a61e71ade5506e..b21defaedc31312147423bd3c051d9a34b472973 100644 (file)
--- a/src/doc/rustdoc/src/command-line-arguments.md
+++ b/src/doc/rustdoc/src/command-line-arguments.md
@@ -100,7 +100,7 @@ By default, `rustdoc` assumes that the name of your crate is the same name
 as the `.rs` file. `--crate-name` lets you override this assumption with
 whatever name you choose.
 
-## `-L`/`--library-path`: 
+## `-L`/`--library-path`: where to look for dependencies
 
 Using this flag looks like this:
 
@@ -141,6 +141,31 @@ Similar to `--library-path`, `--extern` is about specifying the location
 of a dependency. `--library-path` provides directories to search in, `--extern`
 instead lets you specify exactly which dependency is located where.
 
+## `-C`/`--codegen`: pass codegen options to rustc
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc src/lib.rs -C target_feature=+avx
+$ rustdoc src/lib.rs --codegen target_feature=+avx
+
+$ rustdoc --test src/lib.rs -C target_feature=+avx
+$ rustdoc --test src/lib.rs --codegen target_feature=+avx
+
+$ rustdoc --test README.md -C target_feature=+avx
+$ rustdoc --test README.md --codegen target_feature=+avx
+```
+
+When rustdoc generates documentation, looks for documentation tests, or executes documentation
+tests, it needs to compile some rust code, at least part-way. This flag allows you to tell rustdoc
+to provide some extra codegen options to rustc when it runs these compilations. Most of the time,
+these options won't affect a regular documentation run, but if something depends on target features
+to be enabled, or documentation tests need to use some additional options, this flag allows you to
+affect that.
+
+The arguments to this flag are the same as those for the `-C` flag on rustc. Run `rustc -C help` to
+get the full list.
+
 ## `--passes`: add more rustdoc passes
 
 Using this flag looks like this:
@@ -153,7 +178,7 @@ $ rustdoc src/lib.rs --passes strip-priv-imports
 An argument of "list" will print a list of possible "rustdoc passes", and other
 arguments will be the name of which passes to run in addition to the defaults.
 
-For more details on passes, see [the chapter on them](passes.html).
+For more details on passes, see [the chapter on them](passes.md).
 
 See also `--no-defaults`.
 
@@ -169,7 +194,7 @@ By default, `rustdoc` will run several passes over your code. This
 removes those defaults, allowing you to use `--passes` to specify
 exactly which passes you want.
 
-For more details on passes, see [the chapter on them](passes.html).
+For more details on passes, see [the chapter on them](passes.md).
 
 See also `--passes`.
 
@@ -182,11 +207,11 @@ $ rustdoc src/lib.rs --test
 ```
 
 This flag will run your code examples as tests. For more, see [the chapter
-on documentation tests](documentation-tests.html).
+on documentation tests](documentation-tests.md).
 
 See also `--test-args`.
 
-## `--test-args`: 
+## `--test-args`: pass options to test runner
 
 Using this flag looks like this:
 
@@ -195,11 +220,11 @@ $ rustdoc src/lib.rs --test --test-args ignored
 ```
 
 This flag will pass options to the test runner when running documentation tests.
-For more, see [the chapter on documentation tests](documentation-tests.html).
+For more, see [the chapter on documentation tests](documentation-tests.md).
 
 See also `--test`.
 
-## `--target`: 
+## `--target`: generate documentation for the specified target triple
 
 Using this flag looks like this:
 
@@ -279,7 +304,7 @@ $ rustdoc README.md --markdown-playground-url https://play.rust-lang.org/
 ```
 
 When rendering a Markdown file, this flag gives the base URL of the Rust
-Playround, to use for generating `Run` buttons.
+Playground, to use for generating `Run` buttons.
 
 
 ## `--markdown-no-toc`: don't generate a table of contents
@@ -291,7 +316,7 @@ $ rustdoc README.md --markdown-no-toc
 ```
 
 When generating documentation from a Markdown file, by default, `rustdoc` will
-generate a table of contents. This flag supresses that, and no TOC will be
+generate a table of contents. This flag suppresses that, and no TOC will be
 generated.
 
 
@@ -320,3 +345,17 @@ $ rustdoc src/lib.rs --sysroot /path/to/sysroot
 
 Similar to `rustc --sysroot`, this lets you change the sysroot `rustdoc` uses
 when compiling your code.
+
+### `--edition`: control the edition of docs and doctests
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc src/lib.rs --edition 2018
+$ rustdoc --test src/lib.rs --edition 2018
+```
+
+This flag allows rustdoc to treat your rust code as the given edition. It will compile doctests with
+the given edition as well. As with `rustc`, the default edition that `rustdoc` will use is `2015`
+(the first edition).
+