Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
tidy: Run tidy style against markdown files.
  • Loading branch information
ehuss committed Feb 4, 2021
1 parent e708cbd commit bb22eaf
Show file tree
Hide file tree
Showing 38 changed files with 176 additions and 138 deletions.
@@ -1,4 +1,3 @@

Lexical Region Resolution was removed in https://github.com/rust-lang/rust/pull/64790.

Rust now uses Non-lexical lifetimes. For more info, please see the [borrowck
Expand Down
2 changes: 1 addition & 1 deletion src/doc/rustc/src/exploit-mitigations.md
Expand Up @@ -378,7 +378,7 @@ C library default allocator<sup id="fnref:5" role="doc-noteref"><a
href="#fn:5" class="footnote">5</a></sup> since version 1.32.0
(2019-01-17)[39].

```ignore
```rust,no_run
fn main() {
let mut x = Box::new([0; 1024]);
Expand Down
4 changes: 2 additions & 2 deletions src/doc/rustc/src/lints/levels.md
Expand Up @@ -62,7 +62,7 @@ warning: unused variable: `x`
A 'deny' lint produces an error if you violate it. For example, this code
runs into the `exceeding_bitshifts` lint.

```rust,ignore
```rust,no_run
fn main() {
100u8 << 10;
}
Expand Down Expand Up @@ -232,7 +232,7 @@ pub fn foo() {}
This is the maximum level for all lints. So for example, if we take our
code sample from the "deny" lint level above:
```rust,ignore
```rust,no_run
fn main() {
100u8 << 10;
}
Expand Down
2 changes: 1 addition & 1 deletion src/doc/rustc/src/lints/listing/index.md
Expand Up @@ -2,4 +2,4 @@

This section lists out all of the lints, grouped by their default lint levels.

You can also see this list by running `rustc -W help`.
You can also see this list by running `rustc -W help`.
4 changes: 2 additions & 2 deletions src/doc/rustc/src/what-is-rustc.md
Expand Up @@ -39,7 +39,7 @@ $ .\hello.exe # on Windows
Note that we only ever pass `rustc` the *crate root*, not every file we wish
to compile. For example, if we had a `main.rs` that looked like this:

```rust,ignore
```rust,ignore (needs-multiple-files)
mod foo;
fn main() {
Expand All @@ -49,7 +49,7 @@ fn main() {

And a `foo.rs` that had this:

```rust,ignore
```rust,no_run
pub fn hello() {
println!("Hello, world!");
}
Expand Down
5 changes: 2 additions & 3 deletions src/doc/rustdoc/src/advanced-features.md
Expand Up @@ -47,16 +47,15 @@ all type errors and name resolution errors with function bodies. Note that this
work for anything outside a function body: since Rustdoc documents your types, it has to
know what those types are! For example, this code will work regardless of the platform:

<!-- `ignore` because doc-tests are run with `rustc`, not `rustdoc` -->
```ignore
```rust,ignore (platform-specific)
pub fn f() {
use std::os::windows::ffi::OsStrExt;
}
```

but this will not, because the unknown type is part of the function signature:

```ignore
```rust,ignore (platform-specific)
pub fn f() -> std::os::windows::ffi::EncodeWide<'static> {
unimplemented!()
}
Expand Down
20 changes: 13 additions & 7 deletions src/doc/rustdoc/src/documentation-tests.md
Expand Up @@ -5,12 +5,13 @@ that examples within your documentation are up to date and working.

The basic idea is this:

```ignore
```rust,no_run
/// # Examples
///
/// ```
/// let x = 5;
/// ```
# fn f() {}
```
The triple backticks start and end code blocks. If this were in a file named `foo.rs`,
Expand Down Expand Up @@ -78,12 +79,13 @@ Sometimes, you need some setup code, or other things that would distract
from your example, but are important to make the tests work. Consider
an example block that looks like this:

```ignore
```rust,no_run
/// ```
/// /// Some documentation.
/// # fn foo() {} // this function will be hidden
/// println!("Hello, World!");
/// ```
# fn f() {}
```
It will render like this:
Expand Down Expand Up @@ -196,12 +198,13 @@ When writing an example, it is rarely useful to include a complete error
handling, as it would add significant amounts of boilerplate code. Instead, you
may want the following:

```ignore
```rust,no_run
/// ```
/// use std::io;
/// let mut input = String::new();
/// io::stdin().read_line(&mut input)?;
/// ```
# fn f() {}
```
The problem is that `?` returns a `Result<T, E>` and test functions don't
Expand All @@ -210,7 +213,7 @@ return anything, so this will give a mismatched types error.
You can get around this limitation by manually adding a `main` that returns
`Result<T, E>`, because `Result<T, E>` implements the `Termination` trait:
```ignore
```rust,no_run
/// A doc test using ?
///
/// ```
Expand All @@ -222,12 +225,13 @@ You can get around this limitation by manually adding a `main` that returns
/// Ok(())
/// }
/// ```
# fn f() {}
```
Together with the `# ` from the section above, you arrive at a solution that
appears to the reader as the initial idea but works with doc tests:
```ignore
```rust,no_run
/// ```
/// use std::io;
/// # fn main() -> io::Result<()> {
Expand All @@ -236,18 +240,20 @@ appears to the reader as the initial idea but works with doc tests:
/// # Ok(())
/// # }
/// ```
# fn f() {}
```
As of version 1.34.0, one can also omit the `fn main()`, but you will have to
disambiguate the error type:
```ignore
```rust,no_run
/// ```
/// use std::io;
/// let mut input = String::new();
/// io::stdin().read_line(&mut input)?;
/// # Ok::<(), io::Error>(())
/// ```
# fn f() {}
```
This is an unfortunate consequence of the `?` operator adding an implicit
Expand Down Expand Up @@ -417,7 +423,7 @@ Another possible use of `#[cfg(doctest)]` is to test doctests that are included
without including it in your main documentation. For example, you could write this into your
`lib.rs` to test your README as part of your doctests:

```rust,ignore
```rust,no_run
#![feature(external_doc)]
#[doc(include = "../README.md")]
Expand Down
34 changes: 17 additions & 17 deletions src/doc/rustdoc/src/how-to-write-documentation.md
Expand Up @@ -7,7 +7,7 @@ implementation detail, or leaves readers with unanswered questions.

There are a few tenets to Rust documentation that can help guide anyone through
the process of documenting libraries so that everyone has an ample opportunity
to use the code.
to use the code.

This chapter covers not only how to write documentation but specifically
how to write **good** documentation. It is important to be as clear
Expand All @@ -19,39 +19,39 @@ then it should be documented.

Documenting a crate should begin with front-page documentation. As an
example, the [`hashbrown`] crate level documentation summarizes the role of
the crate, provides links to explain technical details, and explains why you
would want to use the crate.
the crate, provides links to explain technical details, and explains why you
would want to use the crate.

After introducing the crate, it is important that the front-page gives
After introducing the crate, it is important that the front-page gives
an example of how to use the crate in a real world setting. Stick to the
library's role in the example, but do so without shortcuts to benefit users who
may copy and paste the example to get started.
may copy and paste the example to get started.

[`futures`] uses inline comments to explain line by line
the complexities of using a [`Future`], because a person's first exposure to
the complexities of using a [`Future`], because a person's first exposure to
rust's [`Future`] may be this example.

The [`backtrace`] documentation walks through the whole process, explaining
The [`backtrace`] documentation walks through the whole process, explaining
changes made to the `Cargo.toml` file, passing command line arguments to the
compiler, and shows a quick example of backtrace in the wild.
compiler, and shows a quick example of backtrace in the wild.

Finally, the front-page can eventually become a comprehensive reference
how to use a crate, like [`regex`]. In this front page, all
requirements are outlined, the edge cases shown, and practical examples
requirements are outlined, the edge cases shown, and practical examples
provided. The front page goes on to show how to use regular expressions
then concludes with crate features.

Don't worry about comparing your crate, which is just beginning, to other more
developed crates. To get the documentation to something more polished, start
incrementally and put in an introduction, example, and features. Rome was not
incrementally and put in an introduction, example, and features. Rome was not
built in a day!

The first lines within the `lib.rs` will compose the front-page, and they
use a different convention than the rest of the rustdocs. Lines should
start with `//!` which indicate module-level or crate-level documentation.
Here's a quick example of the difference:

```rust,ignore
```rust,no_run
//! Fast and easy queue abstraction.
//!
//! Provides an abstraction over a queue. When the abstraction is used
Expand All @@ -64,13 +64,13 @@ Here's a quick example of the difference:
/// This module makes it easy.
pub mod easy {
/// Use the abstract function to do this specific thing.
pub fn abstract() {}
/// Use the abstraction function to do this specific thing.
pub fn abstraction() {}
}
```

Ideally, this first line of documentation is a sentence without highly
Ideally, this first line of documentation is a sentence without highly
technical details, but with a good description of where this crate fits
within the rust ecosystem. Users should know whether this crate meets their use
case after reading this line.
Expand All @@ -95,7 +95,7 @@ It is recommended that each item's documentation follows this basic structure:

This basic structure should be straightforward to follow when writing your
documentation; while you might think that a code example is trivial,
the examples are really important because they can help users understand
the examples are really important because they can help users understand
what an item is, how it is used, and for what purpose it exists.

Let's see an example coming from the [standard library] by taking a look at the
Expand Down Expand Up @@ -133,7 +133,7 @@ for argument in env::args() {
[`args_os`]: ./fn.args_os.html
``````

Everything before the first empty line will be reused to describe the component
Everything before the first empty line will be reused to describe the component
in searches and module overviews. For example, the function `std::env::args()`
above will be shown on the [`std::env`] module documentation. It is good
practice to keep the summary to one line: concise writing is a goal of good
Expand Down Expand Up @@ -225,7 +225,7 @@ details on the exact syntax supported.
[commonmark markdown specification]: https://commonmark.org/
[commonmark quick reference]: https://commonmark.org/help/
[env::args]: https://doc.rust-lang.org/stable/std/env/fn.args.html
[`Future`]: https://doc.rust-lang.org/std/future/trait.Future.html
[`Future`]: https://doc.rust-lang.org/std/future/trait.Future.html
[`futures`]: https://docs.rs/futures/0.3.5/futures/
[`hashbrown`]: https://docs.rs/hashbrown/0.8.2/hashbrown/
[`regex`]: https://docs.rs/regex/1.3.9/regex/
Expand Down
3 changes: 2 additions & 1 deletion src/doc/rustdoc/src/lints.md
Expand Up @@ -3,10 +3,11 @@
`rustdoc` provides lints to help you writing and testing your documentation. You
can use them like any other lints by doing this:

```rust,ignore
```rust
#![allow(missing_docs)] // allows the lint, no diagnostics will be reported
#![warn(missing_docs)] // warn if there are missing docs
#![deny(missing_docs)] // error if there are missing docs
# //! Crate docs.
```

Here is the list of the lints provided by `rustdoc`:
Expand Down
8 changes: 5 additions & 3 deletions src/doc/rustdoc/src/passes.md
Expand Up @@ -32,8 +32,9 @@ Without this pass, these items will remain in the output.

When you write a doc comment like this:

```rust,ignore
```rust,no_run
/// This is a documentation comment.
# fn f() {}
```

There's a space between the `///` and that `T`. That spacing isn't intended
Expand All @@ -52,9 +53,10 @@ documentation string.

For example:

```rust,ignore
```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
Expand All @@ -68,7 +70,7 @@ This is the second line.

This removes documentation for any non-public items, so for example:

```rust,ignore
```rust,no_run
/// These are private docs.
struct Private;
Expand Down
6 changes: 3 additions & 3 deletions src/doc/rustdoc/src/references.md
Expand Up @@ -3,15 +3,15 @@
There are many great `rustdoc` references out there.
If you know of other great resources, please submit a pull request!

## Official
## Official

- [Learn Rust]
- [Rust By Example]
- [Rust Reference]
- [RFC 1574: More API Documentation Conventions]
- [RFC 1946: Intra Rustdoc Links]

## Community
## Community
- [API Guidelines]
- [Github tagged RFCs]
- [Github tagged issues]
Expand All @@ -28,4 +28,4 @@ If you know of other great resources, please submit a pull request!
[RFC 1946: Intra Rustdoc Links]: https://rust-lang.github.io/rfcs/1946-intra-rustdoc-links.html
[RFC (stalled) front page styleguide]: https://github.com/rust-lang/rfcs/pull/1687
[Rust By Example]: https://doc.rust-lang.org/stable/rust-by-example/meta/doc.html
[Rust Reference]: https://doc.rust-lang.org/stable/reference/comments.html#doc-comments
[Rust Reference]: https://doc.rust-lang.org/stable/reference/comments.html#doc-comments

0 comments on commit bb22eaf

Please sign in to comment.