From 1b08684949719568a12d1cb7480241fbd0e67465 Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Thu, 2 Jun 2022 10:55:43 +0100 Subject: [PATCH] doc_testing.md: clarify tests vs doc-tests --- src/testing/doc_testing.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/testing/doc_testing.md b/src/testing/doc_testing.md index 642cbe8a58..cdd32cd01f 100644 --- a/src/testing/doc_testing.md +++ b/src/testing/doc_testing.md @@ -3,7 +3,7 @@ The primary way of documenting a Rust project is through annotating the source code. Documentation comments are written in [markdown] and support code blocks in them. Rust takes care about correctness, so these code blocks are -compiled and used as tests. +compiled and used as documentation tests. ```rust,ignore /// First line is a short summary describing function. @@ -48,7 +48,8 @@ pub fn div(a: i32, b: i32) -> i32 { } ``` -Tests can be run with `cargo test`: +Code blocks in documentation are automatically tested +when running the regular `cargo test` command: ```shell $ cargo test @@ -73,8 +74,8 @@ the functionality, which is one of the most important [guidelines][question-instead-of-unwrap]. It allows using examples from docs as complete code snippets. But using `?` makes compilation fail since `main` returns `unit`. The ability to hide some source lines from documentation comes -to the rescue: one may write `fn try_main() -> Result<(), ErrorType>`, hide it and -`unwrap` it in hidden `main`. Sounds complicated? Here's an example: +to the rescue: one may write `fn try_main() -> Result<(), ErrorType>`, hide it +and `unwrap` it in hidden `main`. Sounds complicated? Here's an example: ```rust,ignore /// Using hidden `try_main` in doc tests.