rustdoc book doc example error

[csditchfield]

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

	``````text
	/// Example
	/// ```rust
	/// let fourtytwo = "42".parse::<u32>()?;
	/// println!("{} + 10 = {}", fourtytwo, fourtytwo+10);
	/// ```
	``````

and

rust/src/doc/rustdoc/src/write-documentation/what-to-include.md

Lines 73 to 82 in 1c05d50

	``````text
	/// Example
	/// ```rust
	/// # main() -> Result<(), std::num::ParseIntError> {
	/// let fortytwo = "42".parse::<u32>()?;
	/// println!("{} + 10 = {}", fortytwo, fortytwo+10);
	/// # Ok(())
	/// # }
	/// ```
	``````

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

lib.txt