什麼是 rustdoc？

標準的 Rust 散佈版會附帶一個名為 rustdoc 的工具。它的工作是為 Rust 專案生成文件。從根本上來說，Rustdoc 接受一個軟體箱根目錄或 Markdown 檔案作為引數，並生成 HTML、CSS 和 JavaScript。

Basic usage

讓我們來試試看！使用 Cargo 建立一個新專案：

$ cargo new docs --lib
$ cd docs

在 src/lib.rs 中，Cargo 已經生成了一些範例程式碼。請將其刪除並替換為以下內容：

#![allow(unused)]
fn main() {
/// foo is a function
fn foo() {}
}

Let’s run rustdoc on our code. To do so, we can call it with the path to our crate root like this:

$ rustdoc src/lib.rs

This will create a new directory, doc, with a website inside! In our case, the main page is located in doc/lib/index.html. If you open that up in a web browser, you will see a page with a search bar, and “Crate lib” at the top, with no contents.

您也可以使用 cargo doc 來為整個專案生成文件。請參見搭配 Cargo 使用 rustdoc。

Configuring rustdoc

這裡有兩個問題：首先，為什麼它認為我們的軟體箱名稱是「lib」？其次，為什麼沒有任何內容？

The first problem is due to rustdoc trying to be helpful; like rustc, it assumes that our crate’s name is the name of the file for the crate root. To fix this, we can pass in a command-line flag:

$ rustdoc src/lib.rs --crate-name docs

Now, doc/docs/index.html will be generated, and the page says “Crate docs.”

For the second issue, it is because our function foo is not public; rustdoc defaults to generating documentation for only public functions. If we change our code…

#![allow(unused)]
fn main() {
/// foo is a function
pub fn foo() {}
}

… and then re-run rustdoc:

$ rustdoc src/lib.rs --crate-name docs

We now have some generated documentation. Open up doc/docs/index.html and check it out! It should show a link to the foo function’s page, which is located at doc/docs/fn.foo.html. On that page, you’ll see the “foo is a function” we put inside the documentation comment in our crate.

搭配 Cargo 使用 rustdoc

Cargo also has integration with rustdoc to make it easier to generate docs. Instead of the rustdoc command, we could have done this:

$ cargo doc

If you want cargo to automatically open the generated documentation, you can use:

$ cargo doc --open

Internally, cargo doc calls out to rustdoc like this:

$ rustdoc --crate-name docs src/lib.rs -o <path>/docs/target/doc -L
dependency=<path>/docs/target/debug/deps

You can see this with cargo doc --verbose.

It generates the correct --crate-name for us, as well as pointing to src/lib.rs. But what about those other arguments?

-o controls the _o_utput of our docs. Instead of a top-level doc directory, notice that Cargo puts generated documentation under target. That is the idiomatic place for generated files in Cargo projects.
-L flag helps rustdoc find the dependencies your code relies on. If our project used dependencies, we would get documentation for them as well!

外部與內部文件

The /// syntax is used to document the item present after it. That’s why it is called an outer documentation. There is another syntax: //!, which is used to document the item it is present inside. It is called an inner documentation. It is often used when documenting the entire crate, because nothing comes before it: it is the root of the crate. So in order to document an entire crate, you need to use //! syntax. For example:

#![allow(unused)]
fn main() {
//! This is my first rust crate
}

When used in the crate root, it documents the item it is inside, which is the crate itself.

For more information about the //! syntax, see the Book.

使用獨立的 Markdown 檔案

rustdoc can also generate HTML from standalone Markdown files. Let’ s give it a try: create a README.md file with these contents:

# Docs

This is a project to test out `rustdoc`.

[Here is a link!](https://www.rust-lang.org)

## Example

```rust
fn foo() -> i32 {
    1 + 1
}
```

並對其執行 rustdoc：

$ rustdoc README.md

你將會在 docs/doc/README.html 中找到一個由其 Markdown 內容生成的 HTML 檔案。

Cargo currently does not understand standalone Markdown files, unfortunately.

Summary

This covers the simplest use-cases of rustdoc. The rest of this book will explain all of the options that rustdoc has, and how to use them.

Keyboard shortcuts