Rollup merge of rust-lang#48961 - Songbird0:rustdoc_doctests_assertio…

…ns, r=GuillaumeGomez

Rustdoc: example of use of assertions

I added this section at the beginning of the file because it seems to be basic information. Let me know if there's someplace more relevant.

See rust-lang#47945.

src/doc/rustdoc/src/documentation-tests.md

@@ -35,6 +35,22 @@ let x = 5;
 
 There's some subtlety though! Read on for more details.
 
+## Passing or failing a doctest
+
+Like regular unit tests, regular doctests are considered to "pass"
+if they compile and run without panicking.
+So if you want to demonstrate that some computation gives a certain result,
+the `assert!` family of macros works the same as other Rust code:
+
+```rust
+let foo = "foo";
+
+assert_eq!(foo, "foo");
+```
+
+This way, if the computation ever returns something different,
+the code panics and the doctest fails.
+
 ## Pre-processing examples
 
 In the example above, you'll note something strange: there's no `main`