Description
Location
rust/src/doc/rustdoc/src/write-documentation/what-to-include.md
The two examples of doc examples in the "Examples" section.
rust/src/doc/rustdoc/src/write-documentation/what-to-include.md
Lines 61 to 67 in 1c05d50
and
rust/src/doc/rustdoc/src/write-documentation/what-to-include.md
Lines 73 to 82 in 1c05d50
Summary
This section of the rustdoc book is explaining at a very high level how to write example code within docs and deals specifically with how Results should be handled within examples.
The first example that the rustdoc book provides is intended to fail:
/// Example
/// ```rust
/// let fourtytwo = "42".parse::<u32>()?;
/// println!("{} + 10 = {}", fourtytwo, fourtytwo+10);
/// ```
The second example is intended to correct the mistakes of the first:
/// Example
/// ```rust
/// # main() -> Result<(), std::num::ParseIntError> {
/// let fortytwo = "42".parse::<u32>()?;
/// println!("{} + 10 = {}", fortytwo, fortytwo+10);
/// # Ok(())
/// # }
/// ```
Unfortunately, this second example fails doc-tests too:
error: expected one of `.`, `;`, `?`, `}`, or an operator, found `->`
--> src\lib.rs:10:8
|
3 | main() -> Result<(), std::num::ParseIntError> {
| ^^ expected one of `.`, `;`, `?`, `}`, or an operator
error: aborting due to previous error
Couldn't compile the test.
To fix this error as simply as possible, a fn should be added to the definition of main:
/// Example
/// ```rust
/// # fn main() -> Result<(), std::num::ParseIntError> {
/// let fortytwo = "42".parse::<u32>()?;
/// println!("{} + 10 = {}", fortytwo, fortytwo+10);
/// # Ok(())
/// # }
/// ```
alternatively, a more modern implementation compatible with 1.34 could be considered:
/// Example
/// ```rust
/// let fortytwo = "42".parse::<u32>()?;
/// println!("{} + 10 = {}", fortytwo, fortytwo+10);
/// # Ok::<(), <u32 as std::str::FromStr>::Err>(())
/// ```
I have included a file (lib.txt) that includes examples using all four of these implementations.
When cargo tested, it produces the following output:
Doc-tests rust_sandbox
running 4 tests
test src\lib.rs - fiz (line 9) ... FAILED
test src\lib.rs - foo (line 2) ... FAILED
test src\lib.rs - buz (line 29) ... ok
test src\lib.rs - baz (line 19) ... ok
failures:
---- src\lib.rs - fiz (line 9) stdout ----
error: expected one of `.`, `;`, `?`, `}`, or an operator, found `->`
--> src\lib.rs:10:8
|
3 | main() -> Result<(), std::num::ParseIntError> {
| ^^ expected one of `.`, `;`, `?`, `}`, or an operator
error: aborting due to previous error
Couldn't compile the test.
---- src\lib.rs - foo (line 2) stdout ----
error[E0277]: the `?` operator can only be used in a function that returns `Result` or `Option` (or another type that implements `FromResidual`)
--> src\lib.rs:3:36
|
2 | fn main() { #[allow(non_snake_case)] fn _doctest_main_src_lib_rs_2_0() {
| --------------------------------- this function should return `Result` or `Option` to accept `?`
3 | let fourtytwo = "42".parse::<u32>()?;
| ^ cannot use the `?` operator in a function that returns `()`
|
= help: the trait `FromResidual<Result<Infallible, ParseIntError>>` is not implemented for `()`
error: aborting due to previous error
For more information about this error, try `rustc --explain E0277`.
Couldn't compile the test.
failures:
src\lib.rs - fiz (line 9)
src\lib.rs - foo (line 2)
test result: FAILED. 2 passed; 2 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.19s
error: doctest failed, to rerun pass `--doc`
Cargo-Process exited abnormally with code 101 at Sat Oct 21 21:00:42