diff --git a/src/doc/rustdoc/src/SUMMARY.md b/src/doc/rustdoc/src/SUMMARY.md index 943aa09f678d7..ae94527e2b4ca 100644 --- a/src/doc/rustdoc/src/SUMMARY.md +++ b/src/doc/rustdoc/src/SUMMARY.md @@ -8,7 +8,7 @@ - [Documentation tests](documentation-tests.md) - [Linking to items by name](linking-to-items-by-name.md) - [Lints](lints.md) -- [Passes](passes.md) - [Advanced features](advanced-features.md) - [Unstable features](unstable-features.md) +- [Passes](passes.md) - [References](references.md) diff --git a/src/doc/rustdoc/src/command-line-arguments.md b/src/doc/rustdoc/src/command-line-arguments.md index 0302fbecb6ed0..2e4016e24bc3f 100644 --- a/src/doc/rustdoc/src/command-line-arguments.md +++ b/src/doc/rustdoc/src/command-line-arguments.md @@ -57,23 +57,6 @@ release: 1.17.0 LLVM version: 3.9 ``` -## `-r`/`--input-format`: input format - -This flag is currently ignored; the idea is that `rustdoc` would support various -input formats, and you could specify them via this flag. - -Rustdoc only supports Rust source code and Markdown input formats. If the -file ends in `.md` or `.markdown`, `rustdoc` treats it as a Markdown file. -Otherwise, it assumes that the input file is Rust. - - -## `-w`/`--output-format`: output format - -This flag is currently ignored; the idea is that `rustdoc` would support -various output formats, and you could specify them via this flag. - -Rustdoc only supports HTML output, and so this flag is redundant today. - ## `-o`/`--output`: output path Using this flag looks like this: @@ -100,6 +83,25 @@ 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. +## `--document-private-items`: Show items that are not public + +Using this flag looks like this: + +```bash +$ rustdoc src/lib.rs --document-private-items +``` + +By default, `rustdoc` only documents items that are publicly reachable. + +```rust +pub fn public() {} // this item is public and will documented +mod private { // this item is private and will not be documented + pub fn unreachable() {} // this item is public, but unreachable, so it will not be documented +} +``` + +`--document-private-items` documents all items, even if they're not public. + ## `-L`/`--library-path`: where to look for dependencies Using this flag looks like this: @@ -166,38 +168,6 @@ 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: - -```bash -$ rustdoc --passes list -$ 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.md). - -See also `--no-defaults`. - -## `--no-defaults`: don't run default passes - -Using this flag looks like this: - -```bash -$ rustdoc src/lib.rs --no-defaults -``` - -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.md). - -See also `--passes`. - ## `--test`: run code examples as tests Using this flag looks like this: @@ -429,3 +399,21 @@ If you specify `@path` on the command-line, then it will open `path` and read command line options from it. These options are one per line; a blank line indicates an empty option. The file can use Unix or Windows style line endings, and must be encoded as UTF-8. + +## `--passes`: add more rustdoc passes + +This flag is **deprecated**. +For more details on passes, see [the chapter on them](passes.md). + +## `--no-defaults`: don't run default passes + +This flag is **deprecated**. +For more details on passes, see [the chapter on them](passes.md). + +## `-r`/`--input-format`: input format + +This flag is **deprecated** and **has no effect**. + +Rustdoc only supports Rust source code and Markdown input formats. If the +file ends in `.md` or `.markdown`, `rustdoc` treats it as a Markdown file. +Otherwise, it assumes that the input file is Rust. diff --git a/src/doc/rustdoc/src/passes.md b/src/doc/rustdoc/src/passes.md index 140b832f19a54..c3c3fd3068ec4 100644 --- a/src/doc/rustdoc/src/passes.md +++ b/src/doc/rustdoc/src/passes.md @@ -3,86 +3,9 @@ Rustdoc has a concept called "passes". These are transformations that `rustdoc` runs on your documentation before producing its final output. -In addition to the passes below, check out the docs for these flags: +Customizing passes is **deprecated**. The available passes are not considered stable and may +change in any release. -* [`--passes`](command-line-arguments.md#--passes-add-more-rustdoc-passes) -* [`--no-defaults`](command-line-arguments.md#--no-defaults-dont-run-default-passes) - -## Default passes - -By default, rustdoc will run some passes, namely: - -* `strip-hidden` -* `strip-private` -* `collapse-docs` -* `unindent-comments` - -However, `strip-private` implies `strip-priv-imports`, and so effectively, -all passes are run by default. - -## `strip-hidden` - -This pass implements the `#[doc(hidden)]` attribute. When this pass runs, it -checks each item, and if it is annotated with this attribute, it removes it -from `rustdoc`'s output. - -Without this pass, these items will remain in the output. - -## `unindent-comments` - -When you write a doc comment like this: - -```rust,no_run -/// This is a documentation comment. -# fn f() {} -``` - -There's a space between the `///` and that `T`. That spacing isn't intended -to be a part of the output; it's there for humans, to help separate the doc -comment syntax from the text of the comment. This pass is what removes that -space. - -The exact rules are left under-specified so that we can fix issues that we find. - -Without this pass, the exact number of spaces is preserved. - -## `collapse-docs` - -With this pass, multiple `#[doc]` attributes are converted into one single -documentation string. - -For example: - -```rust,no_run -#[doc = "This is the first line."] -#[doc = "This is the second line."] -# fn f() {} -``` - -Gets collapsed into a single doc string of - -```text -This is the first line. -This is the second line. -``` - -## `strip-private` - -This removes documentation for any non-public items, so for example: - -```rust,no_run -/// These are private docs. -struct Private; - -/// These are public docs. -pub struct Public; -``` - -This pass removes the docs for `Private`, since they're not public. - -This pass implies `strip-priv-imports`. - -## `strip-priv-imports` - -This is the same as `strip-private`, but for `extern crate` and `use` -statements instead of items. +In the past the most common use case for customizing passes was to omit the `strip-private` pass. +You can do this more easily, and without risk of the pass being changed, by passing +[`--document-private-items`](./unstable-features.md#--document-private-items). diff --git a/src/doc/rustdoc/src/unstable-features.md b/src/doc/rustdoc/src/unstable-features.md index b43070510413a..7d1845dc9578e 100644 --- a/src/doc/rustdoc/src/unstable-features.md +++ b/src/doc/rustdoc/src/unstable-features.md @@ -340,6 +340,30 @@ Some methodology notes about what rustdoc counts in this metric: Public items that are not documented can be seen with the built-in `missing_docs` lint. Private items that are not documented can be seen with Clippy's `missing_docs_in_private_items` lint. +## `-w`/`--output-format`: output format + +When using +[`--show-coverage`](https://doc.rust-lang.org/nightly/rustdoc/unstable-features.html#--show-coverage-get-statistics-about-code-documentation-coverage), +passing `--output-format json` will display the coverage information in JSON format. For example, +here is the JSON for a file with one documented item and one undocumented item: + +```rust +/// This item has documentation +pub fn foo() {} + +pub fn no_documentation() {} +``` + +```json +{"no_std.rs":{"total":3,"with_docs":1,"total_examples":3,"with_examples":0}} +``` + +Note that the third item is the crate root, which in this case is undocumented. + +When not using `--show-coverage`, `--output-format json` emits documentation in the experimental +[JSON format](https://github.com/rust-lang/rfcs/pull/2963). `--output-format html` has no effect, +and is also accepted on stable toolchains. + ### `--enable-per-target-ignores`: allow `ignore-foo` style filters for doctests Using this flag looks like this: