Dokumentation

Angenommen, Sie veröffentlichen eine Bibliothek und möchten am Anfang der Datei lib.rs eine Dokumentation über die gesamte Bibliothek schreiben. Die Dokumentation sollte mit der folgenden Kommentarsyntax beginnen:

//! ist für die Dokumentation auf Modulebene geeignet, während /// für die Dokumentation einzelner Elemente wie Funktionen verwendet wird.

Angenommen, Sie erstellen eine Bibliothek worldly mit der folgenden Funktion in lib.rs:

    /// Fügt den String "world" zu `s` hinzu.
    ///
    /// # Example
    /// ```
    /// let mut s = String::new();
    /// worldly::add_world(&mut s);
    /// assert_eq!(s, "Hello world");
    /// ```
    pub fn add_world(s: &mut String) {
        s.push_str("world");
    }

    #[test]
    fn test_add_world() {
        let mut s = String::new();
        add_world(&mut s);
        assert_eq!(s, "world");
    }

Das inkorrekte Beispiel wird als Dokumentationstest ausgeführt und führt dazu, dass cargo test fehlschlägt.

Angenommen, Sie veröffentlichen eine Bibliothek foobar v0.1.0 . Nachdem Sie cargo publish ausgeführt haben, stellen Sie fest, dass sich ein Fehler in einer Ihrer Funktionen befindet. Welche der folgenden Aussagen beschreibt am besten, wie Sie die veröffentlichte Crate mit derselben Version v0.1.0 überschreiben können?

Crates.io erlaubt das Überschreiben veröffentlichter Versionen nicht. Die beste Option in solchen Situationen ist es, die fehlerhafte Version zu ‘yanken’ (zurückzuziehen) und dann eine neue Version wie v0.1.1 zu veröffentlichen.

Welcher der folgenden Schritte ist NICHT erforderlich, um eine Crate auf Crates.io zu veröffentlichen?

Das Hinzufügen von Dokumentation zu öffentlichen Funktionen wird sicherlich empfohlen, ist aber standardmäßig nicht erforderlich. Beachten Sie, dass, wenn Sie möchten, dass Rust undokumentierten Code als Fehler behandelt, Sie die folgende Anweisung im Stammverzeichnis Ihrer Bibliothek hinzufügen können:

#![deny(missing_docs)]

Dokumentation

Bibliotheksdokumentation Syntax

Cargo Test Fehler

Crate-Version überschreiben

Crate auf Crates.io veröffentlichen