3 ms·
I first learned this from python docstrings, which can include testable examples. I think rust improves on how it’s achieved, but I’m more familiar with how go
by bstpierre 4y ago
I first learned this from python docstrings, which can include testable examples.
I think rust improves on how it’s achieved, but I’m more familiar with how go does it.
Whichever language you use I agree that it’s a great way to ensure that the docs match the package. One thing I would love to see more of is annotations in docstrings that specify when changes were made to packages. (E.g. “version 2.3, added FooFrob()”) Python standard lib does a good job of this, but I can’t think of a convenient (for developers) way to enforce this with tooling.
- tialaramex 4y agoRust's own standard library is annotated like this (examples are from parts of Vec for whatever that's worth): #[stable(feature = "vec_splice", since = "1.21.0")] This annotation is on the splice method, Vec::splice() is a thing from version 1.21.0 onwards #[unstable(feature = "allocator_api", issue = "32838")] Asking for your Vec to use a different allocator instead of the global heap allocator is a nightly feature, ask for feature "allocator_api" in your nightly compiler, or read GitHub issue 32838 if you find problems. #[rustc_const_stable(feature = "const_vec_new", since = "1.39.0")] Vec::new() is compile time constant from 1.39.0, before that a call to Vec::new() actually calls that new() function at runtime, even though a new Vec doesn't allocate anywhere to put anything. If you're currenty in a compile time constant context Vec::new() won't compile at all until 1.39.0