-
Notifications
You must be signed in to change notification settings - Fork 13.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Auto merge of #66323 - JohnTitor:rollup-jl8xdk4, r=JohnTitor
Rollup of 11 pull requests Successful merges: - #65965 (Clean up librustc_typeck error_codes file) - #66230 (remove vestigial comments referring to defunct numeric trait hierarchy) - #66241 (bump openssl version) - #66257 (Drop long-section-names linker workaround for windows-gnu) - #66263 (make the error message more readable) - #66267 (Add rustdoc doc) - #66276 (Move lock into CodeStats) - #66278 (Fix error message about exported symbols from proc-macro crates) - #66280 (Fix HashSet::union performance) - #66299 (support issue = "none" in unstable attributes ) - #66309 (Tiny cleanup to size assertions) Failed merges: r? @ghost
- Loading branch information
Showing
29 changed files
with
458 additions
and
190 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,8 +1,10 @@ | ||
# The Rustdoc Book | ||
|
||
- [What is rustdoc?](what-is-rustdoc.md) | ||
- [How to write documentation](how-to-write-documentation.md) | ||
- [Command-line arguments](command-line-arguments.md) | ||
- [The `#[doc]` attribute](the-doc-attribute.md) | ||
- [Documentation tests](documentation-tests.md) | ||
- [Lints](lints.md) | ||
- [Passes](passes.md) | ||
- [Unstable features](unstable-features.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,82 @@ | ||
# How to write documentation | ||
|
||
This chapter covers not only how to write documentation but specifically | ||
how to write **good** documentation. Something to keep in mind when | ||
writing documentation is that your audience is not just yourself but others | ||
who simply don't have the context you do. It is important to be as clear | ||
as you can, and as complete as possible. As a rule of thumb: the more | ||
documentation you write for your crate the better. If an item is public | ||
then it should be documented. | ||
|
||
## Basic structure | ||
|
||
It is recommended that each item's documentation follows this basic structure: | ||
|
||
```text | ||
[short sentence explaining what it is] | ||
[more detailed explanation] | ||
[at least one code example that users can copy/paste to try it] | ||
[even more advanced explanations if necessary] | ||
``` | ||
|
||
This basic structure should be straightforward to follow when writing your | ||
documentation and, while you might think that a code example is trivial, | ||
the examples are really important because they can help your users to | ||
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 | ||
[`std::env::args()`][env::args] function: | ||
|
||
``````text | ||
Returns the arguments which this program was started with (normally passed | ||
via the command line). | ||
The first element is traditionally the path of the executable, but it can be | ||
set to arbitrary text, and may not even exist. This means this property should | ||
not be relied upon for security purposes. | ||
On Unix systems shell usually expands unquoted arguments with glob patterns | ||
(such as `*` and `?`). On Windows this is not done, and such arguments are | ||
passed as-is. | ||
# Panics | ||
The returned iterator will panic during iteration if any argument to the | ||
process is not valid unicode. If this is not desired, | ||
use the [`args_os`] function instead. | ||
# Examples | ||
``` | ||
use std::env; | ||
// Prints each argument on a separate line | ||
for argument in env::args() { | ||
println!("{}", argument); | ||
} | ||
``` | ||
[`args_os`]: ./fn.args_os.html | ||
`````` | ||
|
||
As you can see, it follows the structure detailed above: it starts with a short | ||
sentence explaining what the functions does, then it provides more information | ||
and finally provides a code example. | ||
|
||
## Markdown | ||
|
||
`rustdoc` is using the [commonmark markdown specification]. You might be | ||
interested into taking a look at their website to see what's possible to do. | ||
|
||
## Lints | ||
|
||
To be sure that you didn't miss any item without documentation or code examples, | ||
you can take a look at the rustdoc lints [here][rustdoc-lints]. | ||
|
||
[standard library]: https://doc.rust-lang.org/stable/std/index.html | ||
[env::args]: https://doc.rust-lang.org/stable/std/env/fn.args.html | ||
[commonmark markdown specification]: https://commonmark.org/ | ||
[rustdoc-lints]: lints.md |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,119 @@ | ||
# Lints | ||
|
||
`rustdoc` provides lints to help you writing and testing your documentation. You | ||
can use them like any other lints by doing this: | ||
|
||
```rust,ignore | ||
#![allow(missing_docs)] // allowing the lint, no message | ||
#![warn(missing_docs)] // warn if there is missing docs | ||
#![deny(missing_docs)] // rustdoc will fail if there is missing docs | ||
``` | ||
|
||
Here is the list of the lints provided by `rustdoc`: | ||
|
||
## intra_doc_link_resolution_failure | ||
|
||
This lint **warns by default** and is **nightly-only**. This lint detects when | ||
an intra-doc link fails to get resolved. For example: | ||
|
||
```rust | ||
/// I want to link to [`Inexistent`] but it doesn't exist! | ||
pub fn foo() {} | ||
``` | ||
|
||
You'll get a warning saying: | ||
|
||
```text | ||
error: `[`Inexistent`]` cannot be resolved, ignoring it... | ||
``` | ||
|
||
## missing_docs | ||
|
||
This lint is **allowed by default**. It detects items missing documentation. | ||
For example: | ||
|
||
```rust | ||
#![warn(missing_docs)] | ||
|
||
pub fn undocumented() {} | ||
# fn main() {} | ||
``` | ||
|
||
The `undocumented` function will then have the following warning: | ||
|
||
```text | ||
warning: missing documentation for a function | ||
--> your-crate/lib.rs:3:1 | ||
| | ||
3 | pub fn undocumented() {} | ||
| ^^^^^^^^^^^^^^^^^^^^^ | ||
``` | ||
|
||
## missing_doc_code_examples | ||
|
||
This lint is **allowed by default**. It detects when a documentation block | ||
is missing a code example. For example: | ||
|
||
```rust | ||
#![warn(missing_doc_code_examples)] | ||
|
||
/// There is no code example! | ||
pub fn no_code_example() {} | ||
# fn main() {} | ||
``` | ||
|
||
The `no_code_example` function will then have the following warning: | ||
|
||
```text | ||
warning: Missing code example in this documentation | ||
--> your-crate/lib.rs:3:1 | ||
| | ||
LL | /// There is no code example! | ||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
``` | ||
|
||
To fix the lint, you need to add a code example into the documentation block: | ||
|
||
```rust | ||
/// There is no code example! | ||
/// | ||
/// ``` | ||
/// println!("calling no_code_example..."); | ||
/// no_code_example(); | ||
/// println!("we called no_code_example!"); | ||
/// ``` | ||
pub fn no_code_example() {} | ||
``` | ||
|
||
## private_doc_tests | ||
|
||
This lint is **allowed by default**. It detects documentation tests when they | ||
are on a private item. For example: | ||
|
||
```rust | ||
#![warn(private_doc_tests)] | ||
|
||
mod foo { | ||
/// private doc test | ||
/// | ||
/// ``` | ||
/// assert!(false); | ||
/// ``` | ||
fn bar() {} | ||
} | ||
# fn main() {} | ||
``` | ||
|
||
Which will give: | ||
|
||
```text | ||
warning: Documentation test in private item | ||
--> your-crate/lib.rs:4:1 | ||
| | ||
4 | / /// private doc test | ||
5 | | /// | ||
6 | | /// ``` | ||
7 | | /// assert!(false); | ||
8 | | /// ``` | ||
| |___________^ | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.