On: The slow march of progress in programming language tooling

[bstpierre]

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 → bstpierre]

Rust'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