Update rustdoc documentation
- Remove most of the information about passes. Passes are deprecated. - Add `--document-private-items`; it was missing before. - Update `--output-format json`; it was very outdated. - Note that `--input-format` is deprecated. - Move deprecated options to the very end. - Move `passes.html` to the end of the table of contents. Ideally it would be removed altogether, but that causes mdbook not to generate the docs.
This commit is contained in:
Joshua Nelson
parent
4f20caa625
commit
dbdaa12486
@ -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)
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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).
|
||||
|
||||
@ -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:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user