Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update rustdoc documentation #82690

Merged
merged 1 commit into from
Mar 5, 2021
+67 −132
Merged

Update rustdoc documentation #82690

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/doc/rustdoc/src/SUMMARY.md
View file
Open in desktop
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
Open in desktop
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe a note on the fact it is very useful when developing the library or binary crate that is being documented, not as a user of said library/binary ? I don't know if that's a good place to put such a tip

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, does that need explanation? It seems pretty self-evident to me.


## `-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
Open in desktop
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
Open in desktop
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
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn't strictly an unstable option, but it's useless except on nightly, so I moved it here.


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