DEV Community

Burdette Lamar
Burdette Lamar

Posted on

Rust: Assertions in API doc?

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?

Top comments (2)

Collapse
 
chayimfriedman2 profile image
Chayim Friedman

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".

Collapse
 
burdettelamar profile image
Burdette Lamar

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.