Programmiersprache: Rust 1.48 pflegt die Dokumentation

Das Rust-Team hat Version 1.48 der ursprünglich von Mozilla ins Leben gerufenen Programmiersprache veröffentlicht. Nachdem der im Oktober erschienene Vorgänger in erster Linie die Toolchain im Blick hatte, konzentriert sich das aktuelle Release auf die Dokumentation über Rustdoc. Daneben sind einige APIs in der Library von Rust stabilisiert, darunter der Versuch, einen Vektor in ein Array mit einer vorgegebenen Länge umzuwandeln.

Rustdoc ist ein Werkzeug, mit dem Entwicklerinnen und Entwickler automatisiert Dokumentationen für ihre Rust-Programme erstellen – analog zu Javadoc im Java-Universum. Das Tool rustdoc ist fester Bestandteil der Rust-Distribution. Es verarbeitet standardmäßig Kommentare, die mit drei Slashes starten: /// Hier steht eine Beschreibung für die nachfolgende Funktion. Daneben existiert die Schreibweise //! für die sogenannte innere Dokumentation, um beispielsweise ein Rust-Paket (Crate) zu dokumentieren

Richtig verlinkt

Die Beschreibung erfolgt im Markdown-Format und ermöglicht unter anderem das Verlinken der Inhalte untereinander. Bisher mussten Entwicklerinnen und Entwickler die Links manuell integrieren und pflegen. Das aktuelle Release führt eine Syntax ein, mit der das Dokumentationswerkzeug sich um die passenden Verweise kümmert, wie folgendes Beispiel aus dem Rust-Blog zeigt:

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;
}

Für den ersten Block erstellt rustdoc den passenden Link zu Bar und für den zweiten umgekehrt den Link zum oben dokumentierten Foo. Der kleine Unterschied in der Syntax zeigt als Text für den oberen Link Bar an, aber für den unteren crate::foo::Foo.

Unter anderem Namen

Eine weitere Ergänzung für die Dokumentation sind sogenannte Search Aliases, die über #[doc(alias = "<alias>")] definieren, dass eine Suche in Rustdoc nach der im <alias> definierten Zeichenkette das darauf folgende Element einbezieht:

#[doc(alias = "bar")]
struct Foo;

Der Code legt fest, dass bei einer Suche nach "bar" das Element Foo zu den passenden Ergebnissen gehört. Als Beispiel für den Einsatz nennt der Blogbeitrag das Einbinden von C-Funktionen über das Foreign Function Interface (ffi), um die passende Zuordnung einer C-Library-Funktion zu der entsprechenden Rust-Funktion zu deklarieren.

Stabile Umwandlung

Bei den stabilisierten APIs in der Standard-Library von Rust ist vor allem die Umwandlung eines Vektors in ein Array fester Länge nennenswert. Allerdings funktioniert das Übertragen nur, wenn der Vektor die passende Größe hat, wie folgendes Beispiel zeigt:

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");

Die obere Überführung eines Vektors mit drei Elementen in ein Array der Größe 3 funktioniert. Dagegen scheitert der zweite Versuch, ein Vec mit fünf Elementen in ein Array mit drei Plätzen zu pressen. Der Blog erwähnt in dem Zusammenhang der stabilisierten API die bereits im vorherigen Rust-Release angestoßene Stabilisierung von Const Generics und verspricht weitere Infos dazu.

Lesen Sie auch

Entwicklung: Warum Rust die Antwort auf miese Software und Programmierfehler ist

Daneben gelten im aktuellen Release die in der Standard-Library definierten APIs slice::as_ptr_range, slice::as_mut_ptr_range, VecDeque::make_contiguous, future::pending und future::ready als stabil. Die bereits stabilen APIs Option::is_some, Option::is_none, Option::as_ref, Result::is_ok, Result::is_err, Result::as_ref, Ordering::reverse und Ordering::then sind nun const.

Weitere Details zu Rust 1.48 lassen sich dem Rust-Blog entnehmen. Die vollständige Liste der Neuerungen steht in den Release Notes. Die aktuelle Version lässt sich wie üblich mit dem Tool rustup durch rustup update stable installieren.

(rme)