One crucial thing about Rust's documentation is that your examples are run by the test infrastructure.
This makes logical sense. If the programmer provided an example of how to call some_function() then we should test that example works. If it doesn't work their example was wrong, or some_function() is broken, either way the programmer needs to fix that.
For the test infrastructure to run your examples, they must be code, not some sort of annotation.
The result is now you don't ship documentation which oops, is documenting the old some_function which had different behaviour and so of course that example doesn't work any more. Sorry, we didn't rewrite the docs yet, just go read this Discord thread and the six bug tracker entries it links...
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.
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
This makes logical sense. If the programmer provided an example of how to call some_function() then we should test that example works. If it doesn't work their example was wrong, or some_function() is broken, either way the programmer needs to fix that.
For the test infrastructure to run your examples, they must be code, not some sort of annotation.
The result is now you don't ship documentation which oops, is documenting the old some_function which had different behaviour and so of course that example doesn't work any more. Sorry, we didn't rewrite the docs yet, just go read this Discord thread and the six bug tracker entries it links...