The Rust team is happy to announce a new version of Rust, 1.48.0. Rust is a
programming language that is empowering everyone to build reliable and
efficient software.
If you have a previous version of Rust installed via rustup, getting Rust
1.48.0 is as easy as:
rustup update stable
If you don't have it already, you can get rustup from the
appropriate page on our website, and check out the detailed release notes for
1.48.0 on GitHub.
What's in 1.48.0 stable
The star of this release is Rustdoc, with a few changes to make writing
documentation even easier! See the detailed release notes to learn
about other changes not covered by this post.
Easier linking in rustdoc
Rustdoc, the library documentation tool included in the Rust distribution,
lets you write documentation in Markdown. This makes it very easy to use, but
also has some pain points. Let's say that you are writing some documentation
for some Rust code that looks like this:
pub mod foo {
pub struct Foo;
}
pub mod bar {
pub struct Bar;
}
We have two modules, each with a struct inside. Imagine we wanted to use these
two structs together; we may want to note this in the documentation. So we'd
write some docs that look like this:
pub mod foo {
/// Some docs for `Foo`
///
/// You may want to use `Foo` with `Bar`.
pub struct Foo;
}
pub mod bar {
/// Some docs for Bar
///
/// You may want to use Bar with Foo.
pub struct Bar;
}
That's all well and good, but it would be really nice if we could link to these
other types. That would make it much easier for the users of our library to
navigate between them in our docs.
The problem here is that Markdown doesn't know anything about Rust, and the
URLs that rustdoc generates. So what Rust programmers have had to do is write
those links out manually:
pub mod foo {
/// Some docs for `Foo`
///
/// You may want to use `Foo` with [`Bar`].
///
/// [`Bar`]: ../bar/struct.Bar.html
pub struct Foo;
}
pub mod bar {
/// Some docs for Bar
///
/// You may want to use Bar with [Foo].
///
/// [Foo]: …/foo/struct.Foo.html
pub struct Bar;
}
Note that we've also had to use relative links, so that this works offline.
Not only is this process tedious, and error prone, but it's also just wrong
in places. If we put a pub use bar::Bar in our crate root, that would
re-export Bar in our root. Now our links are wrong. But if we fix them,
then they end up being wrong when we navigate to the Bar that lives inside
the module. You can't actually write these links by hand, and have them all
be accurate.
In this release, you can use some syntax to let rustdoc know that you're
trying to link to a type, and it will generate the URLs for you. Here's
two different examples, based off of our code before:
pub mod foo {
/// Some docs for `Foo`
///
/// You may want to use `Foo` with [`Bar`](crate::bar::Bar).
pub struct Foo;
}
pub mod bar {
/// Some docs for Bar
///
/// You may want to use Bar with [crate::foo::Foo].
pub struct Bar;
}
The first example will show the same text as before; but generate the proper
link to the Bar type. The second will link to Foo, but will show the whole
crate::foo::Foo as the link text.
There are a bunch of options you can use here. Please see the "Linking to
items by name" section of the rustdoc book for more. There is also
a post on Inside Rust on the history of this feature, written
by some of the contributors behind it!
Adding search aliases
You can now specify #[doc(alias = "<alias>")] on items to add search
aliases when searching through rustdoc's UI. This is a smaller change,
but still useful. It looks like this:
#[doc(alias = "bar")]
struct Foo;
With this annotation, if we search for "bar" in rustdoc's search, Foo will
come up as part of the results, even though our search text doesn't have
"Foo" in it.
An interesting use case for aliases is FFI wrapper crates, where each Rust
function could be aliased to the C function it wraps. Existing users of the
underlying C library would then be able to easily search the right Rust
functions!
Library changes
The most significant API change is kind of a mouthful: [T; N]: TryFrom<Vec<T>>
is now stable. What does this mean? Well, you can use this to try and turn
a vector into an array of a given length:
use std::convert::TryInto;
let v1: Vec<u32> = vec![1, 2, 3];
// This will succeed; our vector has a length of three, we’re trying to
// make an array of length three.
let a1: [u32; 3] = v1.try_into().expect("wrong length");
// But if we try to do it with a vector of length five…
let v2: Vec<u32> = vec![1, 2, 3, 4, 5];
// … this will panic, since we have the wrong length.
let a2: [u32; 3] = v2.try_into().expect("wrong length");
In the last release, we talked about the standard library being able to use
const generics. This is a good example of the kinds of APIs that we can add
with these sorts of features. Expect to hear more about the stabilization of
const generics soon.
Additionally, five new APIs were stabilized this release:
The following previously stable APIs have now been made const:
See the detailed release notes for more.
Other changes
There are other changes in the Rust 1.48.0 release: check out what changed in
Rust, Cargo, and Clippy.
Contributors to 1.48.0
Many people came together to create Rust 1.48.0. We couldn't have done it
without all of you. Thanks!
