Easy Rust

cargo doc 命令

你可能已經注意到，Rust 文件看起來總是幾乎一樣。在左邊你可以見到 struct 和 trait，程式碼範例在右邊等等。這是因為你只要輸入 cargo doc 就可以自動產生文件。

即使是建立一個什麼都不做的專案，也可以幫助你瞭解 Rust 中的特徵。例如，這裡有兩個幾乎什麼都不做的結構體，以及一個也什麼都不做的 fn main()。

struct DoesNothing {}
struct PrintThing {}

impl PrintThing {
    fn prints_something() {
        println!("I am printing something");
    }
}

fn main() {}

但如果你輸入 cargo doc --open，你可以見到比你預期更多的資訊。首先它秀出這些給你：

Crate rust_book

Structs
DoesNothing
PrintThing

Functions
main

但是如果你點選其中的一個結構體，會讓你看到很多你想都沒想到過的特徵：

Struct rust_book::DoesNothing
[+] Show declaration
Auto Trait Implementations
impl RefUnwindSafe for DoesNothing
impl Send for DoesNothing
impl Sync for DoesNothing
impl Unpin for DoesNothing
impl UnwindSafe for DoesNothing
Blanket Implementations
impl<T> Any for T
where
    T: 'static + ?Sized,
[src]
[+]
impl<T> Borrow<T> for T
where
    T: ?Sized,
[src]
[+]
impl<T> BorrowMut<T> for T
where
    T: ?Sized,
[src]
[+]
impl<T> From<T> for T
[src]
[+]
impl<T, U> Into<U> for T
where
    U: From<T>,
[src]
[+]
impl<T, U> TryFrom<U> for T
where
    U: Into<T>,
[src]
[+]
impl<T, U> TryInto<U> for T
where
    U: TryFrom<T>,

這是因為 Rust 自動為每個型別所實作的所有特徵。

那麼如果我們新增一些文件註解，當你輸入 cargo doc 的時候就可以看到。

/// This is a struct that does nothing
struct DoesNothing {}
/// This struct only has one method.
struct PrintThing {}
/// It just prints the same message.
impl PrintThing {
    fn prints_something() {
        println!("I am printing something");
    }
}

fn main() {}

現在會印出：

Crate rust_book
Structs
DoesNothing This is a struct that does nothing
PrintThing  This struct only has one method.
Functions
main

當你使用很多別人的 crate 時，cargo doc 就非常友善。因為這些 crate 全部都在不同的網站上，可能需要花些時間來搜尋所有的 crate。但如果你使用 cargo doc，你就會擁有它們全部，而且被放在你硬碟裡的同個地方。