Wie kann ich kistenweite Dokumentation schreiben?

Question

Um sicherzustellen, dass alle öffentlichen Artefakte meiner Kiste dokumentiert sind (wenn minimal zu Beginn), spezifizierte ich #![deny(missing_docs)] in meinem lib.rs, aber es fehlte.

Ich erwartete, Code zu schreiben, wie so, dass Dokumentationskommentar an der Spitze und der Code ist danach:

/// Hello world example for Rust. 

#![deny(missing_docs)] 

fn main() { 
    println!("Hello world!"); 
} 

Dies schlägt mit:

3:3: 3:4 error: an inner attribute is not permitted in this context 
3 #![deny(missing_docs)] 

den Auftrag zurückkehrend, Attribute erste und Kommentar Zweitens:

#![deny(missing_docs)] 

/// Hello world example for Rust. 

fn main() { 
    println!("Hello world!"); 
} 

auch nicht:

1:1: 7:1 error: missing documentation for crate 
1 #![deny(missing_docs)] 

und nirgendwo in der book's Documentation section finde ich, wie man eigentlich Dokumentation für die Kiste selbst schreibt.

Also, wie sollte ich die Kiste Dokumentation schreiben, um #![deny(missing_docs)] zu erfüllen?

Answer 1

Ich fand tatsächlich das versteckte Nugget in book's Documentation section.

Regelmäßige Dokumentation Kommentare (beginnend mit ///) dokumentieren die nächste Artikel, aber eine Kiste ist niemandes nächsten.

Die Lösung ist daher auf die Verwendung einer anderen Art von Kommentar zu wechseln, diesmal mit //! beginnen, die die umschließenden Artikel dokumentiert.

Und es funktioniert plötzlich:

#![deny(missing_docs)] 

//! Hello world example for Rust. 

fn main() { 
    println!("Hello world!"); 
}