I've looked a bit at the API documentation for Rust. I was surprised to see that very often the documentation for a method uses one or more assertions about the returned value, instead of showing the returned value itself.
This contrasts sharply with corresponding documentation for other languages. Does anyone know the motivation for this?
- Rust.
- Ruby (btw, I wrote this one).
- Python.
- Javascript.
- C++.
Top comments (2)
There is a good reason for that: cargo test checks doctests too. If the method will break, the doctest will panic and the build will break. This is like more unit tests. This also serves as a proof that the documentation is correct, AKA "if it compiles, it works".
Interesting. I've done something similar in a Ruby project (don't remember which one -- I'm 79), by having a Rake task that makes the doc by running examples, then including the code and output into the doc.