Blog

Rustdoc: Hướng Dẫn Dành Cho Người Mới Bắt Đầu Về Tài Liệu API Trong Rust

中村 拓也

中村 拓也

3 tháng 11 2025

Rustdoc: Hướng Dẫn Dành Cho Người Mới Bắt Đầu Về Tài Liệu API Trong Rust

Apidog cho doanh nghiệp

Triển khai tại chỗ

SSO & RBAC

Tuân thủ SOC 2

Khám phá Apidog Enterprise

Tài liệu đóng vai trò như cầu nối giữa các nhà phát triển và người dùng mã nguồn của họ. Trong hệ sinh thái Rust, tài liệu được nâng tầm thành công dân hạng nhất thông qua Rustdoc, một công cụ tạo tài liệu tinh vi đi kèm với bản phát hành Rust tiêu chuẩn. Khác với các công cụ tài liệu trong nhiều ngôn ngữ khác, Rustdoc không chỉ đơn thuần tạo ra tài liệu tĩnh—nó tạo ra các trang web tài liệu tương tác, có thể kiểm tra và định dạng phong phú giúp nâng cao khả năng phát hiện mã và tính khả dụng.

Đối với các nhà phát triển Rust, Apidog cung cấp các tính năng tài liệu API toàn diện cho API HTTP với khả năng thử nghiệm tương tác, định dạng phản hồi hình ảnh và các chức năng hợp tác.

button

Apidog tập trung vào việc tài liệu hóa các điểm cuối, định dạng yêu cầu/phản hồi và các đặc tả HTTP, trong khi Rustdoc chuyên môn hóa vào việc tài liệu hóa mã nguồn ở cấp độ ngôn ngữ—tài liệu hóa các cấu trúc, hàm, trait và các cấu trúc lập trình khác tạo thành một crate Rust. Cả hai hệ thống đều chia sẻ mục tiêu cơ bản là làm cho các hệ thống kỹ thuật phức tạp trở nên dễ tiếp cận hơn thông qua tài liệu đầy đủ, chính xác và có thể sử dụng được.

button

Rustdoc là gì?

Rustdoc là một công cụ dòng lệnh phân tích mã nguồn Rust và các chú thích tài liệu đặc biệt để tạo ra các tệp HTML, CSS và JavaScript tạo thành một trang web tài liệu có thể duyệt được. Về cốt lõi, Rustdoc hoạt động bằng cách trích xuất các chú thích tài liệu từ mã của bạn và chuyển đổi chúng thành tài liệu có cấu trúc.

Hoạt động cơ bản của Rustdoc bao gồm:

  1. Phân tích các tệp nguồn Rust để trích xuất các chú thích tài liệu
  2. Chuyển đổi các chú thích đó từ Markdown sang HTML
  3. Tạo ra một cấu trúc trang web có thể tìm kiếm và điều hướng
  4. Trích xuất các ví dụ mã từ tài liệu và chuẩn bị chúng cho việc kiểm tra
  5. Tạo các liên kết chéo giữa các mục
  6. Sản xuất các tài sản tĩnh cho tài liệu cuối cùng

Khi được gọi trực tiếp, nhị phân Rustdoc chấp nhận một tệp nguồn Rust làm đầu vào:

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

Ủy quyền này xử lý tệp lib.rs và xuất tài liệu vào thư mục doc theo mặc định. Tài liệu được cấu trúc phân cấp, phản ánh cấu trúc mã của bạn, với các trang riêng biệt cho các mô-đun, cấu trúc, enum, trait và các cấu trúc Rust khác.

Ở phía trong, Rustdoc tận dụng các API nội bộ của trình biên dịch Rust để phân tích và hiểu mã của bạn. Sự tích hợp chặt chẽ này với trình biên dịch cho phép Rustdoc tạo ra các liên kết chéo chính xác, tài liệu hóa đúng chữ ký kiểu và xác minh rằng các ví dụ mã thực sự biên dịch và chạy chính xác.

Chú Thích Tài Liệu trong Rust

Tài liệu trong Rust phụ thuộc vào cú pháp chú thích đặc biệt khác với các chú thích mã thông thường. Có hai loại chú thích tài liệu chính:

Chú Thích Tài Liệu Ngoài (///)

Các chú thích tài liệu ngoài tài liệu hóa mục theo sau chúng và được đánh dấu bằng ba dấu gạch chéo:

/// Đây là một chú thích tài liệu cho hàm bên dưới.
/// Nó có thể trải dài nhiều dòng và hỗ trợ định dạng Markdown.
pub fn documented_function() -> bool {
    true
}

Các chú thích này mô tả các hàm, cấu trúc, enum, trait và các mục khác trong mã của bạn. Chúng được gọi là "các chú thích ngoài" vì tồn tại ngoài mục mà chúng tài liệu hóa.

Chú Thích Tài Liệu Trong (//!)

Các chú thích tài liệu trong tài liệu hóa mục mà chúng xuất hiện bên trong và được đánh dấu bằng //!:

//! Mô-đun này cung cấp tiện ích cho việc phân tích các tệp cấu hình.
//!
//! # Ví dụ
//!
//! ```
//! let config = my_crate::config::parse("config.toml");
//! assert!(config.is_ok());
//! ```

pub fn parse(file_path: &str) -> Result<Config, ParseError> {
    // Triển khai ở đây
}

Các chú thích tài liệu trong thường được sử dụng cho tài liệu cấp mô-đun hoặc crate. Khi đặt ở đầu tệp lib.rs, chúng tài liệu hóa toàn bộ crate và tạo thành trang chính của tài liệu được tạo ra.

Khác biệt kỹ thuật giữa các kiểu chú thích này là rất mơ hồ nhưng quan trọng: /// tài liệu hóa những gì theo sau nó, trong khi //! tài liệu hóa những gì chứa nó.

Hỗ Trợ Markdown trong Rustdoc

Rustdoc sử dụng trình phân tích Markdown tuân thủ CommonMark với nhiều phần mở rộng. Điều này cung cấp cho các tác giả tài liệu quyền truy cập vào một bộ tùy chọn định dạng phong phú:

Định Dạng Cơ Bản

/// # Tiêu đề Cấp 1
/// ## Tiêu đề Cấp 2
///
/// Các đoạn được phân cách bằng các dòng trống.
///
/// *Văn bản nghiêng* và **văn bản đậm** được hỗ trợ.
///
/// - Danh sách không có thứ tự
/// - Có thể được tạo
/// - Như thế này
///
/// 1. Danh sách có thứ tự
/// 2. Cũng hoạt động tốt
///
/// `Mã nội tuyến` được bao quanh bởi dấu nháy đơn.

Khối Mã

Các khối mã vô cùng quan trọng trong Rustdoc vì chúng phục vụ hai mục đích: chúng hiển thị các ví dụ mã trong tài liệu và có thể được trích xuất dưới dạng thử nghiệm.

/// ```rust
/// // Đây là một khối mã
/// let x = 5;
/// assert_eq!(x, 5);
/// ```

Theo mặc định, nếu không có ngôn ngữ nào được chỉ định sau các dấu nháy đơn ba, Rustdoc cho rằng khối mã chứa mã Rust. Tuy nhiên, bạn có thể chỉ định các ngôn ngữ khác để tô sáng cú pháp:

/// ```json
/// {
///     "name": "example",
///     "version": "1.0.0"
/// }
/// ```

Các Phần Mở Rộng Rustdoc

Rustdoc mở rộng CommonMark với một số tính năng bổ sung:

Văn bản Gạch Chéo

/// ~~Văn bản gạch chéo~~ sử dụng dấu tildes.

Chú Thích

/// Câu này cần làm rõ[^1].
///
/// [^1]: Đây là sự làm rõ.

Bảng

/// | Tiêu đề1 | Tiêu đề2 |
/// |---------|---------|
/// | ô1   | ô2   |
/// | ô3   | ô4   |

Danh Sách Nhiệm Vụ

/// - [x] Nhiệm vụ đã hoàn thành
/// - [ ] Nhiệm vụ chưa hoàn thành

Dấu Chấm Thông Minh

Rustdoc tự động chuyển đổi các chuỗi dấu câu ASCII sang các biến thể Unicode của chúng:

Giao Diện Dòng Lệnh Rustdoc Chi Tiết

Rustdoc cung cấp một bộ tùy chọn dòng lệnh toàn diện cho việc tùy chỉnh việc tạo tài liệu:

$ rustdoc --help

Một số tùy chọn quan trọng về mặt kỹ thuật bao gồm:

Đối với một dự án có phụ thuộc bên ngoài, một lệnh Rustdoc điển hình có thể trông như:

$ rustdoc src/lib.rs --crate-name example_crate \
  --edition=2021 \
  -L dependency=target/debug/deps \
  --extern serde=target/debug/deps/libserde-abcd1234.rlib \
  --extern tokio=target/debug/deps/libtokio-efgh5678.rlib

May mắn thay, Cargo tự động hóa quá trình phức tạp này với một lệnh đơn giản:

$ cargo doc --document-private-items

Tích Hợp với Cargo

Cargo cung cấp một giao diện gọn nhẹ để làm việc với Rustdoc thông qua lệnh cargo doc. Nội bộ, Cargo gọi Rustdoc với các tham số phù hợp:

$ cargo doc --verbose

Chạy lệnh này sẽ hiển thị các gọi Rustdoc thực tế, tiết lộ cách mà Cargo cấu hình các đường dẫn đến các phụ thuộc và thư mục đầu ra.

Chức năng cốt lõi bao gồm:

Cargo thông minh xác định tên crate từ tệp Cargo.toml của bạn, thiết lập cấu trúc thư mục đầu ra chính xác dưới target/doc/, và đảm bảo tất cả các phụ thuộc được liên kết đúng cách.

Cấu Trúc và Tổ Chức Tài Liệu

Tài liệu Cấp crate

Tài liệu cấp crate đóng vai trò là trang đích cho thư viện của bạn và nên cung cấp cái nhìn tổng quan toàn diện. Điều này được viết dưới dạng tài liệu trong (//!) ở đầu tệp lib.rs:

//! # Thư viện Mã Hóa Nâng Cao Của Tôi
//!
//! Crate này cung cấp các phần tử mã hóa với trọng tâm vào:
//!
//! - **Hiệu suất**: Các triển khai tối ưu cho CPU hiện đại
//! - **Bảo mật**: Các thuật toán được xác minh chính thức
//! - **Khả năng sử dụng**: Các API hạng cao, khó sử dụng sai
//!
//! ## Khởi động Nhanh
//!
//! ```rust
//! sử dụng crypto_lib::{Cipher, Mode};
//!
//! let key = crypto_lib::generate_key(256);
//! let cipher = Cipher::new(&key, Mode::GCM);
//!
//! let plaintext = b"Thông điệp bí mật";
//! let ciphertext = cipher.encrypt(plaintext);
//! ```
//!
//! ## Tính năng
//!
//! Crate hỗ trợ các thuật toán sau:
//!
//! - AES (128, 192, 256)
//! - ChaCha20
//! - Poly1305
//! - HMAC
//! - PBKDF2

Tài liệu cấp crate hiệu quả thường bao gồm:

  1. Một mô tả ngắn gọn, một câu về mục đích của crate
  2. Giải thích chi tiết về các khái niệm và tính năng chính
  3. Các ví dụ khởi động nhanh cho thấy việc sử dụng cơ bản
  4. Tổng quan về kiến trúc cho các thư viện phức tạp hơn
  5. Các cờ tính năng và tùy chọn cấu hình
  6. Thông tin tương thích
  7. Đặc điểm hiệu suất

Tài liệu Cấp mô-đun

Các mô-đun hoạt động như các đơn vị tổ chức trong Rust và nên có tài liệu riêng giải thích mục đích và nội dung của chúng:

pub mod symmetric {
    //! Các thuật toán mã hóa đối xứng.
    //!
    //! Mô-đun này cung cấp các triển khai của các thuật toán mã hóa khối và dòng,
    //! các thuật toán mã hóa xác thực và các tiện ích liên quan.
    //!
    //! # Cân nhắc Bảo mật
    //!
    //! Tất cả các triển khai đã được kiểm toán bởi [Công ty Bảo mật]
    //! và được xác minh chính thức bằng cách sử dụng [Công cụ Xác minh].

    /// Triển khai thuật toán mã khối AES với hỗ trợ cho các khóa 128, 192 và 256-bit.
    pub struct Aes {
        // Các trường ở đây
    }

    // Các mục khác...
}

Tài liệu Cấp mục

Các mục riêng lẻ như cấu trúc, hàm và trait nên có tài liệu tập trung giải thích mục đích, cách sử dụng và bất kỳ cân nhắc đặc biệt nào:

/// Một bộ tạo số ngẫu nhiên an toàn về mặt mật mã.
///
/// CSPRNG này sử dụng nguồn entropy của hệ thống để tạo ra
/// các byte ngẫu nhiên phù hợp cho các hoạt động mật mã.
///
/// # Ví dụ
///
/// ```
/// sử dụng crypto_lib::CSPRNG;
///
/// let mut rng = CSPRNG::new();
/// let random_bytes = rng.generate_bytes(32);
/// ```
///
/// # Bảo mật
///
/// Trên Linux, điều này sử dụng getrandom(2) khi có sẵn, ngược lại sẽ rơi vào /dev/urandom.
/// Trên Windows, nó sử dụng BCryptGenRandom.
/// Trên macOS, nó sử dụng SecRandomCopyBytes.
pub struct CSPRNG {
    // Chi tiết triển khai
}

impl CSPRNG {
    /// Tạo một bộ tạo số ngẫu nhiên an toàn về mặt mật mã mới.
    ///
    /// # Panics
    ///
    /// Panics nếu nguồn entropy của hệ thống không khả dụng.
    ///
    /// # Ví dụ
    ///
    /// ```
    /// let rng = crypto_lib::CSPRNG::new();
    /// ```
    pub fn new() -> Self {
        // Triển khai
    }

    /// Tạo ra số lượng byte ngẫu nhiên được chỉ định.
    ///
    /// # Tham số
    ///
    /// * `len` - Số lượng byte ngẫu nhiên để tạo ra
    ///
    /// # Trả về
    ///
    /// Một vector chứa `len` byte ngẫu nhiên an toàn về mặt mật mã.
    ///
    /// # Ví dụ
    ///
    /// ```
    /// sử dụng crypto_lib::CSPRNG;
    ///
    /// let mut rng = CSPRNG::new();
    /// let key_material = rng.generate_bytes(32);
    /// assert_eq!(key_material.len(), 32);
    /// ```
    pub fn generate_bytes(&mut self, len: usize) -> Vec<u8> {
        // Triển khai
    }
}

Thử nghiệm Tài liệu Chi Tiết

Một trong những tính năng mạnh mẽ nhất của Rustdoc là khả năng chạy các ví dụ mã như các thử nghiệm. Điều này đảm bảo rằng:

  1. Các ví dụ trong tài liệu của bạn thực sự biên dịch
  2. Các ví dụ tạo ra kết quả mong đợi
  3. Các ví dụ luôn được cập nhật khi API của bạn phát triển

Khi bạn bao gồm một khối mã Rust trong tài liệu của mình, Rustdoc trích xuất nó và tạo ra một khuôn mẫu thử nghiệm xung quanh nó:

/// Cộng hai số lại với nhau.
///
/// # Ví dụ
///
/// ```
/// let result = my_crate::add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

Ở hậu trường, Rustdoc chuyển đổi điều này thành một tệp thử nghiệm độc lập giống như:

extern crate my_crate;

fn main() {
    let result = my_crate::add(2, 3);
    assert_eq!(result, 5);
}

Tệp này sau đó được biên dịch và thực thi. Nếu chương trình biên dịch và chạy mà không panic, thử nghiệm được tính là thành công.

Tiền xử lý Thử nghiệm

Trước khi chạy thử nghiệm, Rustdoc áp dụng một số biến đổi để làm cho các ví dụ đơn giản trở nên thuận tiện hơn:

  1. Các cảnh báo thông thường như unused_variables và dead_code được cho phép
  2. Nếu ví dụ không chứa extern crate và #![doc(test(no_crate_inject))] không được chỉ định, extern crate <mycrate>; được chèn vào
  3. Nếu ví dụ không chứa fn main, mã được gói trong fn main() { ... }

Các phép biến đổi này cho phép bạn tập trung vào các phần quan trọng của ví dụ mà không cần các mã mẫu.

Kiểm Soát Hành Vi Thử nghiệm

Rustdoc cung cấp một số thuộc tính để kiểm soát cách các thử nghiệm được thực thi:

Ví dụ:

/// ```ignore
/// // Mã này không được kiểm tra
/// let x = function_that_doesnt_exist();
/// ```
///
/// ```should_panic
/// // Mã này nên panic
/// panic!("Ví dụ này chứng minh một panic");
/// ```
///
/// ```compile_fail
/// // Mã này không nên biên dịch
/// let x: i32 = "điều này không nên biên dịch";
/// ```
///
/// ```no_run
/// // Mã này biên dịch nhưng không chạy
/// loop {
///     println!("Điều này sẽ chạy mãi mãi!");
/// }
/// ```
///
/// ```edition2021
/// // Mã này sử dụng các tính năng Rust 2021
/// let result = try {
///     "10".parse::<i32>()?
/// };
/// ```

Sử Dụng ? Trong Các Thử Nghiệm Tài liệu

Bởi vì các ví dụ tài liệu được gói trong một hàm main() trả về (), việc sử dụng toán tử ? yêu cầu xử lý đặc biệt. Có hai cách tiếp cận:

  1. Định nghĩa rõ ràng một hàm main trả về một Result:
/// ```
/// # fn main() -> Result<(), std::io::Error> {
/// let content = std::fs::read_to_string("file.txt")?;
/// println!("Nội dung tệp: {}", content);
/// # Ok(())
/// # }
/// ```

2. Sử dụng chú thích kiểu với Ok(()):

/// ```
/// let content = std::fs::read_to_string("file.txt")?;
/// println!("Nội dung tệp: {}", content);
/// # Ok::<(), std::io::Error>(())
/// ```

Trong cả hai trường hợp, dấu # ở đầu một số dòng ẩn chúng khỏi tài liệu kết xuất nhưng vẫn bao gồm chúng trong thử nghiệm.

Liên Kết đến Các Mục theo Tên

Rustdoc cung cấp một hệ thống tham chiếu chéo mạnh mẽ cho phép các tác giả tài liệu tạo liên kết đến các mục khác trong mã nguồn. Tính năng này làm tăng đáng kể khả năng điều hướng của tài liệu của bạn.

Liên Kết Trong Tài Liệu

Để tạo một liên kết đến một mục khác, sử dụng cú pháp [item_name]:

/// Sử dụng loại [`HashMap`] từ thư viện chuẩn.
///
/// Nó cũng dựa vào hàm [`build_map`] được định nghĩa ở nơi khác trong crate này.
pub fn process_data() {
    // Triển khai
}

/// Tạo một [`HashMap`] mới với các giá trị được định nghĩa trước.
pub fn build_map() -> HashMap<String, i32> {
    // Triển khai
}

Khi Rustdoc xử lý các liên kết này, nó tự động giải quyết chúng đến các mục đúng, tạo ra các siêu liên kết có thể nhấp trong HTML được tạo ra.

Phân Biệt Đường Dẫn

Để liên kết chính xác hơn, đặc biệt khi xử lý các mục có thể có cùng tên trong các mô-đun khác nhau, bạn có thể sử dụng các đường dẫn đầy đủ:

/// Hàm này sử dụng [`std::collections::HashMap`] để lưu trữ
/// và [`crate::utils::format`] để định dạng đầu ra.
pub fn complex_operation() {
    // Triển khai
}

Việc giải quyết đường dẫn tuân theo các quy tắc khả năng nhìn thấy trong Rust, vì vậy bạn chỉ có thể liên kết đến các mục mà sẽ nhìn thấy được từ phạm vi hiện tại.

Mục Liên Kết

Bạn có thể liên kết đến nhiều loại mục khác nhau:

/// Liên kết đến một cấu trúc: [`MyStruct`]
/// Liên kết đến một enum: [`Option`]
/// Liên kết đến một trait: [`Iterator`]
/// Liên kết đến một hàm: [`process_data`]
/// Liên kết đến một phương thức: [`MyStruct::new`]
/// Liên kết đến một mô-đun: [`crate::utils`]
/// Liên kết đến một hằng số: [`MAX_SIZE`]
/// Liên kết đến một bí danh kiểu: [`Result`]

Hệ thống liên kết toàn diện này cho phép các tác giả tài liệu tạo ra một mạng lưới tài liệu liên kết phong phú giúp người dùng điều hướng các API phức tạp.

Các Tính Năng Tài Liệu Nâng Cao

Thuộc tính #[doc]

Thuộc tính #[doc] cung cấp kiểm soát nâng cao đối với việc tạo tài liệu:

// Tương đương với việc sử dụng các chú thích ///
#[doc = "Đây là tài liệu cho mục dưới đây."]
pub struct DocumentedStruct;

// Ẩn một mục khỏi tài liệu
#[doc(hidden)]
pub struct InternalStruct;

// Thêm bí danh tìm kiếm
#[doc(alias = "connection")]
#[doc(alias = "socket")]
pub struct NetworkStream;

Đối với tài liệu có điều kiện dựa trên các cờ tính năng:

/// Hàm này thực hiện những điều tuyệt vời.
///
#[doc = "Giải thích khả năng cơ bản."]
#[cfg_attr(feature = "advanced", doc = "Cũng hỗ trợ chế độ nâng cao khi tính năng 'advanced' được kích hoạt.")]
pub fn do_things() {
    // Triển khai
}

Mẫu Bao Gồm Tài Liệu

Để tái sử dụng nội dung trong các tài liệu:

/// # An toàn
///
#[doc = include_str!("../docs/common_safety_notes.md")]
pub unsafe fn perform_unsafe_operation() {
    // Triển khai
}

Điều này cho phép bạn duy trì các đoạn tài liệu chung trong các tệp riêng biệt và bao gồm chúng tại nơi cần, giảm thiểu sự trùng lặp và đảm bảo tính nhất quán.

Ví dụ bị Trích xuất

Rustdoc có thể tự động trích xuất các ví dụ mã từ các thư mục thử nghiệm và ví dụ của crate của bạn, cung cấp bối cảnh bổ sung cho việc sử dụng API:

$ cargo doc --document-scraped-examples

Tính năng này hoạt động bằng cách quét crate của bạn để tìm cách sử dụng các mục công khai và trích xuất những cách sử dụng đó dưới dạng ví dụ. Nó đặc biệt có giá trị cho các API phức tạp mà các ví dụ tài liệu nội tuyến có thể không đủ.

Tài Liệu Có Điều Kiện

Sử dụng thuộc tính cfg, bạn có thể bao gồm hoặc loại bỏ tài liệu một cách có điều kiện:

#[cfg(target_os = "windows")]
/// Chi tiết cài đặt riêng cho Windows.
pub fn windows_only_function() {
    // Triển khai Windows
}

#[cfg(target_os = "linux")]
/// Chi tiết cài đặt riêng cho Linux.
pub fn linux_only_function() {
    // Triển khai Linux
}

Điều này cho phép bạn tạo tài liệu riêng cho từng nền tảng hoặc tính năng chỉ xuất hiện khi có liên quan.

HTML Tùy Chỉnh trong Tài Liệu

Đối với các nhu cầu định dạng đặc biệt, Rustdoc cho phép nhúng HTML trực tiếp vào tài liệu:

/// <div class="warning">
/// <strong>Cảnh báo:</strong> Hàm này thực hiện I/O và có thể bị chặn.
/// </div>
pub fn blocking_operation() {
    // Triển khai
}

Kết hợp với CSS tùy chỉnh, điều này cho phép định dạng phong phú hơn những gì Markdown cung cấp một mình.

HTML và CSS Tùy Chỉnh

Rustdoc cho phép tùy chỉnh giao diện của tài liệu được tạo ra thông qua HTML và CSS:

Tiền Xử Lý HTML

Bạn có thể thêm HTML tùy chỉnh vào tiêu đề tài liệu:

$ rustdoc src/lib.rs --html-in-header custom-header.html

Điều này hữu ích cho việc thêm các bảng kiểu, thư viện JavaScript hoặc thẻ meta tùy chỉnh.

Tùy Chỉnh CSS

Để áp dụng CSS tùy chỉnh cho tài liệu của bạn:

$ rustdoc src/lib.rs --css custom-styles.css

Tệp CSS của bạn có thể nhắm đến cấu trúc HTML của Rustdoc để tùy chỉnh màu sắc, phông chữ, bố cục, và nhiều thứ khác:

/* Thay đổi màu nền chính */
body {
    background-color: #f5f5f5;
}

/* Định dạng các khối cảnh báo */
.warning {
    background-color: #fff3cd;
    border-left: 4px solid #ffc107;
    padding: 0.5rem 1rem;
    margin: 1rem 0;
}

/* Định dạng tùy chỉnh cho các khối mã */
pre {
    background-color: #282c34;
    border-radius: 6px;
    padding: 1rem;
}

Giao Diện Tùy Chỉnh

Rustdoc hỗ trợ nhiều chủ đề tích hợp sẵn, bao gồm Light, Rust, Coal, Navy và Ayu. Bạn cũng có thể tạo các chủ đề tùy chỉnh:

$ rustdoc src/lib.rs --theme mytheme.css

Các Thực Hành Tốt Nhất Về Tài Liệu

Độ Chính Xác Kỹ Thuật

Tài liệu phải chính xác về mặt kỹ thuật. Xác định hành vi chính xác, các trường hợp đặc biệt và các đặc điểm hiệu suất:

/// Tìm kiếm một phần tử trong một dải đã sắp xếp sử dụng tìm kiếm nhị phân.
///
/// # Độ phức tạp
///
/// Độ phức tạp thời gian: O(log n)
/// Độ phức tạp không gian: O(1)
///
/// # Panics
///
/// Panic nếu dải không được sắp xếp theo thứ tự tăng dần.
///
/// # Ví dụ
///
/// ```
/// let sorted = [1, 2, 3, 4, 5];
/// assert_eq!(my_crate::binary_search(&sorted, 3), Some(2));
/// assert_eq!(my_crate::binary_search(&sorted, 6), None);
/// ```
pub fn binary_search<T: Ord>(slice: &[T], value: T) -> Option<usize> {
    // Triển khai
}

Tài Liệu Có Cấu Trúc

Thực hiện theo một cấu trúc nhất quán cho mỗi loại mục:

Các hàm và phương thức:

Các cấu trúc và enum:

Các trait:

Độ Chính Xác Ngôn Ngữ

Sử dụng ngôn ngữ kỹ thuật chính xác và tránh sự mơ hồ:

Thông Tin Phiên Bản

Tài liệu hóa độ ổn định API và các cân nhắc phiên bản:

/// Xử lý gói mạng theo RFC 1234.
///
/// # Độ ổn định
///
/// Hàm này được coi là ổn định kể từ phiên bản 0.2.0.
///
/// # Sự khác biệt giữa các phiên bản
///
/// Trước phiên bản 0.3.0, hàm này sẽ âm thầm cắt ngắn các gói lớn hơn 1500 byte. Bây giờ nó trả về một lỗi.
pub fn process_packet(packet: &[u8]) -> Result<ProcessedPacket, PacketError> {
    // Triển khai
}

Kỹ Thuật Thử Nghiệm Nâng Cao

Thử Nghiệm Trong Các Môi Trường Khác Nhau

Bạn có thể cấu hình các thử nghiệm tài liệu để chạy với các biến môi trường cụ thể:

/// ```
/// # std::env::set_var("API_KEY", "test_key");
/// let client = my_crate::Client::new_from_env()?;
/// # Ok::<(), my_crate::Error>(())
/// ```

Thử Nghiệm Với Các Tài Nguyên Bên Ngoài

Đối với các thử nghiệm cần tài nguyên bên ngoài, hãy sử dụng thuộc tính no_run và giải thích các yêu cầu:

/// ```no_run
/// // Ví dụ này yêu cầu một cơ sở dữ liệu PostgreSQL tại localhost:5432
/// // với tên người dùng "test" và mật khẩu "test"
/// let db = my_crate::Database::connect(
///     "postgres://test:test@localhost:5432/testdb"
/// )?;
/// # Ok::<(), my_crate::Error>(())
/// ```

Thử Nghiệm Xử Lý Lỗi

Cho thấy cách xử lý lỗi trong API của bạn:

/// ```
/// sử dụng my_crate::{process_data, DataError};
///
/// // Trường hợp thành công
/// let result = process_data(&[1, 2, 3]);
/// assert!(result.is_ok());
///
/// // Trường hợp lỗi
/// let error_result = process_data(&[]);
/// assert!(matches!(error_result, Err(DataError::EmptyInput)));
/// ```

Quốc Tế Hóa và Khả Năng Tiếp Cận

Tài Liệu Không Phải Tiếng Anh

Mặc dù Rustdoc không có hỗ trợ quốc tế hóa tích hợp, bạn có thể cung cấp tài liệu bằng nhiều ngôn ngữ khác nhau bằng cách sử dụng các cờ tính năng:

#[cfg(feature = "docs-en")]
/// Cộng hai số lại với nhau.
#[cfg(feature = "docs-es")]
/// Suma dos números.
#[cfg(feature = "docs-ja")]
/// 二つの数値を足します。
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

Cân Nhắc Khả Năng Tiếp Cận

Viết tài liệu có thể tiếp cận với người dùng khuyết tật:

  1. Cung cấp các lựa chọn văn bản thay thế cho hình ảnh
  2. Đảm bảo độ tương phản màu sắc đầy đủ
  3. Cấu trúc nội dung với các tiêu đề đúng cách
  4. Đảm bảo các ví dụ mã thân thiện với trình đọc màn hình
/// Sơ đồ kiến trúc bên dưới mô tả các thành phần hệ thống:
///
/// ![Sơ đồ Kiến trúc](./images/architecture.png)
/// *Văn bản thay thế: Một sơ đồ lưu đồ hiển thị luồng dữ liệu từ Đầu vào qua Xử lý đến Đầu ra,
/// với các thành phần Cơ sở dữ liệu và Bộ nhớ Cache ở hai bên*

Kết Luận

Rustdoc là một trong những công cụ tài liệu mạnh mẽ và toàn diện nhất trong bất kỳ hệ sinh thái ngôn ngữ lập trình nào. Sự tích hợp chặt chẽ của nó với trình biên dịch Rust, khả năng kiểm tra mạnh mẽ và các tùy chọn định dạng phong phú cho phép các nhà phát triển tạo ra tài liệu không chỉ mang tính mô tả mà còn chính xác, dễ sử dụng và dễ bảo trì.

Bằng cách khai thác toàn bộ khả năng của Rustdoc—từ các chú thích tài liệu cơ bản đến các tính năng nâng cao như biên dịch có điều kiện, HTML/CSS tùy chỉnh, và kiểm tra toàn diện—các nhà phát triển Rust có thể tạo ra tài liệu phục vụ như một tài nguyên học tập và một tài liệu tham khảo đáng tin cậy.

Tài liệu là một khía cạnh cơ bản của thiết kế API và tính khả dụng của phần mềm. Khi được chế tác với sự quan tâm và độ chính xác kỹ thuật sử dụng các khả năng của Rustdoc, nó trở thành một tài sản quý giá giúp giảm bớt độ khó học, ngăn ngừa lỗi và thúc đẩy việc sử dụng đúng cách các thư viện của bạn.

Khi hệ sinh thái Rust tiếp tục phát triển, Rustdoc cũng phát triển cùng với nó, liên tục cải thiện khả năng của nó để đáp ứng nhu cầu của một cơ sở người dùng ngày càng đa dạng và tinh vi. Bằng cách thành thạo Rustdoc, bạn không chỉ cải thiện mã nguồn của riêng bạn mà còn góp phần vào các tiêu chuẩn tài liệu cao giúp biến cộng đồng Rust thành một trong những cộng đồng thân thiện và dễ tiếp cận nhất trong thế giới lập trình.

Câu Hỏi Thường Gặp

1. Làm thế nào tôi có thể gỡ lỗi các thử nghiệm tài liệu đang gặp lỗi?

Câu trả lời: Các thử nghiệm tài liệu có thể được gỡ lỗi bằng một

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API

Đăng ký miễn phíTải xuống