Skip to content

Commit

Permalink
Rollup merge of #82690 - jyn514:remove-pass-docs, r=Manishearth
Browse files Browse the repository at this point in the history 
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.

Closes #82675.

r? `@Manishearth`
  • Loading branch information
@GuillaumeGomez
GuillaumeGomez authored Mar 4, 2021
2 parents 2f28361 + dbdaa12 commit 2a5ecb2
Show file tree
Hide file tree
Showing 4 changed files with 67 additions and 132 deletions.
2 changes: 1 addition & 1 deletion src/doc/rustdoc/src/SUMMARY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
86 changes: 37 additions & 49 deletions src/doc/rustdoc/src/command-line-arguments.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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.
87 changes: 5 additions & 82 deletions src/doc/rustdoc/src/passes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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).
24 changes: 24 additions & 0 deletions src/doc/rustdoc/src/unstable-features.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down

0 comments on commit 2a5ecb2

Please sign in to comment.