Rustdoc: example of use of assertions

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

@@ -31,6 +31,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`