Hello
I am terribly confused by the example here: Documentation testing - Rust By Example
...
/// and `extern crate <cratename>`. Assume we're testing `doccomments` crate:
///
/// ```
/// let result = doccomments::add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
a + b
}
My assumption is that the example likes to comment on pub fn add(a: i32, b: i32) -> i32
and provide an example on how to use it. Cargo test
will then check if the provided example actually works. This concept is new to me.
This is how my test project looks like after some trial, error, online search assumptions to fill in the gabs:
_21_Testing
├── Cargo.lock
├── Cargo.toml
├── src
│ ├── doccomments.rs
│ └── main.rs
└── target
...
Cargo.toml:
[package]
name = "_21_Testing"
version = "0.1.0"
edition = "2021"
# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
[dependencies]
[lib]
path = "src/doccomments.rs"
src/doccomments.rs
:
/// First line is a short summary describing function.
///
/// The next lines present detailed documentation. Code blocks start with
/// triple backquotes and have implicit `fn main()` inside
/// and `extern crate <cratename>`. Assume we're testing `doccomments` crate:
///
/// ```
/// let result = add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
a + b
}
Runing cargo test
includes this output:
...
Doc-tests _21_Testing
running 1 test
test src/doccomments.rs - add (line 7) ... FAILED
failures:
---- src/doccomments.rs - add (line 7) stdout ----
error[E0433]: failed to resolve: use of undeclared crate or module `doccomments`
--> src/doccomments.rs:8:14
|
3 | let result = doccomments::add(2, 3);
| ^^^^^^^^^^^ use of undeclared crate or module `doccomments`
error: aborting due to previous error
...
Simple, i thought to myself as I removed doccomments::
and rerun cargo test
:
...
Doc-tests _21_Testing
running 1 test
test src/doccomments.rs - add (line 7) ... FAILED
failures:
---- src/doccomments.rs - add (line 7) stdout ----
error[E0425]: cannot find function `add` in this scope
--> src/doccomments.rs:8:14
|
3 | let result = add(2, 3);
| ^^^ not found in this scope
|
help: consider importing this function
|
2 | use _21_Testing::add;
|
error: aborting due to previous error
...
At this point, I turned to the search function in this forum and some more online searching, without much luck as I am not sure what to search for. I think I am confused about the environment the documentation code is placed in, and/or how to create a library correctly. Maybe it is something completely different. I am at a loss on how to approach this.