Rustdoc: Panduan Pemula untuk Dokumentasi API di Rust

Dokumentasi berfungsi sebagai jembatan antara pengembang dan pengguna kode mereka. Dalam ekosistem Rust, dokumentasi ditingkatkan menjadi warga kelas satu melalui Rustdoc, alat pembuatan dokumentasi canggih yang disertakan dengan distribusi standar Rust. Tidak seperti alat dokumentasi di banyak bahasa lain, Rustdoc tidak hanya menghasilkan dokumentasi statis—ia membuat situs web dokumentasi interaktif, dapat diuji, dan diformat dengan kaya yang meningkatkan kemampuan penemuan dan kegunaan kode.

Untuk pengembang Rust, Apidog menawarkan fitur dokumentasi API komprehensif untuk API HTTP dengan kemampuan pengujian interaktif, pemformatan respons visual, dan fungsi kolaboratif.

button

Apidog berfokus pada pendokumentasian titik akhir, format permintaan/respons, dan spesifikasi HTTP, Rustdoc mengkhususkan diri dalam mendokumentasikan kode pada tingkat bahasa—mendokumentasikan struct, fungsi, trait, dan konstruksi pemrograman lainnya yang membentuk crate Rust. Kedua sistem berbagi tujuan mendasar untuk membuat sistem teknis yang kompleks lebih mudah diakses melalui dokumentasi yang menyeluruh, akurat, dan dapat digunakan.

button

Apa itu Rustdoc?

Rustdoc adalah alat baris perintah yang mengurai kode sumber Rust dan komentar dokumentasi khusus untuk menghasilkan file HTML, CSS, dan JavaScript yang membentuk situs web dokumentasi yang dapat dijelajahi. Intinya, Rustdoc beroperasi dengan mengekstrak komentar dokumentasi dari kode Anda dan mengubahnya menjadi dokumentasi terstruktur.

Operasi dasar Rustdoc meliputi:

Mengurai file sumber Rust untuk mengekstrak komentar dokumentasi
Mengonversi komentar tersebut dari Markdown ke HTML
Menghasilkan struktur situs web yang dapat dicari dan dinavigasi
Mengekstrak contoh kode dari dokumentasi dan menyiapkannya untuk pengujian
Membuat referensi silang antar item
Menghasilkan aset statis untuk dokumentasi akhir

Saat dipanggil secara langsung, biner Rustdoc menerima file sumber Rust sebagai masukan:

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

Perintah ini memproses file lib.rs dan mengeluarkan dokumentasi ke direktori doc secara default. Dokumentasi disusun secara hierarkis, mencerminkan struktur kode Anda, dengan halaman terpisah untuk modul, struct, enum, trait, dan konstruksi Rust lainnya.

Di balik layar, Rustdoc memanfaatkan API internal kompiler Rust untuk mengurai dan memahami kode Anda. Integrasi yang erat dengan kompiler ini memungkinkan Rustdoc untuk menghasilkan referensi silang yang akurat, mendokumentasikan tanda tangan tipe dengan benar, dan memverifikasi bahwa contoh kode benar-benar dikompilasi dan berjalan dengan benar.

Komentar Dokumentasi di Rust

Dokumentasi di Rust bergantung pada sintaks komentar khusus yang berbeda dari komentar kode biasa. Ada dua jenis utama komentar dokumentasi:

Komentar Dokumentasi Luar (`///`)

Komentar dokumentasi luar mendokumentasikan item yang mengikutinya dan dilambangkan dengan tiga garis miring ke depan:

/// Ini adalah komentar dokumentasi untuk fungsi di bawah ini.
/// Ini dapat mencakup beberapa baris dan mendukung pemformatan Markdown.
pub fn documented_function() -> bool {
    true
}

Komentar ini menjelaskan fungsi, struct, enum, trait, modul, dan item lain dalam basis kode Anda. Mereka disebut dokumentasi "luar" karena mereka berada di luar item yang mereka dokumentasikan.

Komentar Dokumentasi Dalam (`//!`)

Komentar dokumentasi dalam mendokumentasikan item yang muncul di dalamnya dan dilambangkan dengan //!:

//! Modul ini menyediakan utilitas untuk mengurai file konfigurasi.
//!
//! # Contoh
//!
//! ```
//! let config = my_crate::config::parse("config.toml");
//! assert!(config.is_ok());
//! ```

pub fn parse(file_path: &str) -> Result<Config, ParseError> {
    // Implementasi di sini
}

Komentar dokumentasi dalam biasanya digunakan untuk dokumentasi tingkat modul atau tingkat crate. Ketika ditempatkan di awal file lib.rs, mereka mendokumentasikan seluruh crate dan membentuk halaman depan dokumentasi yang dihasilkan.

Perbedaan teknis antara gaya komentar ini halus tetapi penting: /// mendokumentasikan apa yang ada setelahnya, sedangkan //! mendokumentasikan apa yang memuatnya.

Dukungan Markdown di Rustdoc

Rustdoc menggunakan pengurai Markdown yang sesuai dengan CommonMark dengan beberapa ekstensi. Ini memberi penulis dokumentasi akses ke serangkaian opsi pemformatan yang kaya:

Pemformatan Dasar

/// # Tingkat Judul 1
/// ## Tingkat Judul 2
///
/// Paragraf dipisahkan oleh baris kosong.
///
/// *Teks miring* dan **teks tebal** didukung.
///
/// - Daftar tidak berurutan
/// - Dapat dibuat
/// - Seperti ini
///
/// 1. Daftar berurutan
/// 2. Juga berfungsi
///
/// `Kode sebaris` dikelilingi oleh backtick.

Blok Kode

Blok kode sangat penting di Rustdoc karena mereka melayani tujuan ganda: mereka menampilkan contoh kode dalam dokumentasi dan dapat diekstraksi sebagai pengujian.

/// ```rust
/// // Ini adalah blok kode
/// let x = 5;
/// assert_eq!(x, 5);
/// ```

Secara default, jika tidak ada bahasa yang ditentukan setelah tiga backtick pembuka, Rustdoc mengasumsikan blok kode berisi kode Rust. Namun, Anda dapat menentukan bahasa lain untuk penyorotan sintaks:

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

Ekstensi Rustdoc

Rustdoc memperluas CommonMark dengan beberapa fitur tambahan:

Teks Coret

/// ~~Teks coret~~ menggunakan tilde.

Catatan Kaki

/// Pernyataan ini membutuhkan klarifikasi[^1].
///
/// [^1]: Inilah klarifikasinya.

Tabel

/// | Header1 | Header2 |
/// |---------|---------|
/// | cell1   | cell2   |
/// | cell3   | cell4   |

Daftar Tugas

/// - [x] Tugas selesai
/// - [ ] Tugas belum selesai

Tanda Baca Cerdas

Rustdoc secara otomatis mengonversi urutan tanda baca ASCII ke padanan Unicode mereka:

-- menjadi en dash (–)
--- menjadi em dash (—)
... menjadi elipsis (…)
Tanda kutip lurus menjadi tanda kutip keriting

Antarmuka Baris Perintah Rustdoc Terperinci

Rustdoc menawarkan serangkaian opsi baris perintah yang komprehensif untuk menyesuaikan pembuatan dokumentasi:

$ rustdoc --help

Beberapa opsi yang paling signifikan secara teknis meliputi:

--document-private-items: Secara default, Rustdoc hanya mendokumentasikan item publik. Bendera ini menyertakan item pribadi dalam dokumentasi, berguna untuk dokumentasi internal.
--test: Jalankan contoh dokumentasi sebagai pengujian, memverifikasi bahwa mereka dikompilasi dan dieksekusi seperti yang diharapkan.
--test-args: Berikan argumen tambahan ke pelari pengujian, seperti --nocapture untuk menampilkan keluaran dari pengujian.
--edition=EDITION: Tentukan edisi Rust untuk mengurai dan menjalankan kode (2015, 2018, 2021, 2024).
--target=TARGET: Hasilkan dokumentasi untuk platform target yang ditentukan.
--crate-type=TYPE: Tentukan jenis crate untuk pengujian (bin, lib, rlib, dylib, cdylib, staticlib, proc-macro).
-L FLAG=PATH: Tambahkan direktori ke jalur pencarian pustaka, penting untuk menyelesaikan dependensi dalam pengujian.
--cfg=SPEC: Berikan bendera --cfg ke kompiler, memungkinkan kompilasi bersyarat dalam kode dokumentasi.
--extern NAME=PATH: Tentukan lokasi crate eksternal, memungkinkan pengujian untuk mereferensikan dependensi eksternal.

Untuk proyek dengan dependensi eksternal, pemanggilan Rustdoc yang khas mungkin terlihat seperti:

$ 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

Untungnya, Cargo mengotomatiskan proses kompleks ini dengan perintah sederhana:

$ cargo doc --document-private-items

Integrasi dengan Cargo

Cargo menyediakan antarmuka yang disederhanakan untuk bekerja dengan Rustdoc melalui perintah cargo doc. Secara internal, Cargo memanggil Rustdoc dengan parameter yang sesuai:

$ cargo doc --verbose

Menjalankan perintah ini akan menampilkan pemanggilan Rustdoc yang sebenarnya, mengungkapkan bagaimana Cargo mengonfigurasi jalur ke dependensi dan direktori keluaran.

Fungsi inti meliputi:

cargo doc: Hasilkan dokumentasi untuk crate saat ini dan dependensinya
cargo doc --no-deps: Hasilkan dokumentasi hanya untuk crate saat ini
cargo doc --open: Hasilkan dokumentasi dan buka di peramban web
cargo doc --document-private-items: Sertakan item pribadi dalam dokumentasi
cargo test --doc: Jalankan pengujian dokumentasi

Cargo secara cerdas menentukan nama crate dari file Cargo.toml Anda, menyiapkan struktur direktori keluaran yang benar di bawah target/doc/, dan memastikan semua dependensi ditautkan dengan benar.

Struktur dan Organisasi Dokumentasi

Dokumentasi Tingkat Crate

Dokumentasi tingkat crate berfungsi sebagai halaman arahan untuk pustaka Anda dan harus memberikan ikhtisar yang komprehensif. Ini ditulis sebagai dokumentasi dalam (//!) di bagian atas file lib.rs:

//! # Pustaka Kriptografi Tingkat Lanjut Saya
//!
//! Crate ini menyediakan primitif kriptografi dengan fokus pada:
//!
//! - **Kinerja**: Implementasi yang dioptimalkan untuk CPU modern
//! - **Keamanan**: Algoritma yang diverifikasi secara formal
//! - **Kegunaan**: API tingkat tinggi yang sulit disalahgunakan
//!
//! ## Mulai Cepat
//!
//! ```rust
//! use crypto_lib::{Cipher, Mode};
//!
//! let key = crypto_lib::generate_key(256);
//! let cipher = Cipher::new(&key, Mode::GCM);
//!
//! let plaintext = b"Pesan rahasia";
//! let ciphertext = cipher.encrypt(plaintext);
//! ```
//!
//! ## Fitur
//!
//! Crate ini mendukung algoritma berikut:
//!
//! - AES (128, 192, 256)
//! - ChaCha20
//! - Poly1305
//! - HMAC
//! - PBKDF2

Dokumentasi tingkat crate yang efektif sering kali mencakup:

Deskripsi singkat satu kalimat tentang tujuan crate
Penjelasan rinci tentang konsep dan fitur utama
Contoh mulai cepat yang menunjukkan penggunaan dasar
Ikhtisar arsitektur untuk pustaka yang lebih kompleks
Bendera fitur dan opsi konfigurasi
Informasi kompatibilitas
Karakteristik kinerja

Dokumentasi Tingkat Modul

Modul bertindak sebagai unit organisasi di Rust dan harus memiliki dokumentasi sendiri yang menjelaskan tujuan dan isinya:

pub mod symmetric {
    //! Algoritma enkripsi simetris.
    //!
    //! Modul ini menyediakan implementasi blok dan sandi aliran,
    //! algoritma enkripsi terotentikasi, dan utilitas terkait.
    //!
    //! # Pertimbangan Keamanan
    //!
    //! Semua implementasi telah diaudit oleh [Perusahaan Keamanan]
    //! dan diverifikasi secara formal menggunakan [Alat Verifikasi].

    /// Implementasi sandi blok AES dengan dukungan untuk kunci 128, 192, dan 256-bit.
    pub struct Aes {
        // Bidang di sini
    }

    // Lebih banyak item...
}

Dokumentasi Tingkat Item

Item individual seperti struct, fungsi, dan trait harus memiliki dokumentasi terfokus yang menjelaskan tujuan, penggunaan, dan pertimbangan khusus apa pun:

/// Generator angka acak yang aman secara kriptografis.
///
/// CSPRNG ini menggunakan sumber entropi sistem untuk menghasilkan
/// byte acak yang cocok untuk operasi kriptografi.
///
/// # Contoh
///
/// ```
/// use crypto_lib::CSPRNG;
///
/// let mut rng = CSPRNG::new();
/// let random_bytes = rng.generate_bytes(32);
/// ```
///
/// # Keamanan
///
/// Di Linux, ini menggunakan getrandom(2) jika tersedia, kembali ke /dev/urandom.
/// Di Windows, ini menggunakan BCryptGenRandom.
/// Di macOS, ini menggunakan SecRandomCopyBytes.
pub struct CSPRNG {
    // Detail implementasi
}

impl CSPRNG {
    /// Membuat generator angka acak yang aman secara kriptografis baru.
    ///
    /// # Panik
    ///
    /// Panik jika sumber entropi sistem tidak tersedia.
    ///
    /// # Contoh
    ///
    /// ```
    /// let rng = crypto_lib::CSPRNG::new();
    /// ```
    pub fn new() -> Self {
        // Implementasi
    }

    /// Menghasilkan jumlah byte acak yang ditentukan.
    ///
    /// # Argumen
    ///
    /// * `len` - Jumlah byte acak yang akan dihasilkan
    ///
    /// # Mengembalikan
    ///
    /// Vektor yang berisi `len` byte acak yang aman secara kriptografis.
    ///
    /// # Contoh
    ///
    /// ```
    /// use 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> {
        // Implementasi
    }
}

Pengujian Dokumentasi Secara Mendalam

Salah satu fitur Rustdoc yang paling kuat adalah kemampuannya untuk menjalankan contoh kode sebagai pengujian. Ini memastikan bahwa:

Contoh dalam dokumentasi Anda benar-benar dikompilasi
Contoh menghasilkan hasil yang diharapkan
Contoh tetap mutakhir seiring evolusi API Anda

Ketika Anda menyertakan blok kode Rust dalam dokumentasi Anda, Rustdoc mengekstraknya dan membuat kerangka pengujian di sekitarnya:

/// Menambahkan dua angka.
///
/// # Contoh
///
/// ```
/// let result = my_crate::add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

Di balik layar, Rustdoc mengubah ini menjadi file pengujian mandiri yang menyerupai:

extern crate my_crate;

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

File ini kemudian dikompilasi dan dieksekusi. Jika program dikompilasi dan berjalan tanpa panik, pengujian lulus.

Pra-pemrosesan Pengujian

Sebelum menjalankan pengujian, Rustdoc menerapkan beberapa transformasi untuk membuat contoh sederhana lebih ergonomis:

Lint umum seperti unused_variables dan dead_code diizinkan
Jika contoh tidak berisi extern crate dan #![doc(test(no_crate_inject))] tidak ditentukan, extern crate <mycrate>; disisipkan
Jika contoh tidak berisi fn main, kode dibungkus dalam fn main() { ... }

Transformasi ini memungkinkan Anda untuk fokus pada bagian penting dari contoh Anda tanpa boilerplate.

Mengontrol Perilaku Pengujian

Rustdoc menyediakan beberapa atribut untuk mengontrol bagaimana pengujian dieksekusi:

ignore: Kode tidak diuji
should_panic: Kode harus dikompilasi tetapi panik saat dijalankan
compile_fail: Kode tidak boleh dikompilasi
no_run: Kode dikompilasi tetapi tidak dieksekusi
edition2015, edition2018, edition2021: Jalankan kode dengan edisi Rust tertentu

Contoh:

/// ```ignore
/// // Kode ini tidak diuji
/// let x = function_that_doesnt_exist();
/// ```
///
/// ```should_panic
/// // Kode ini seharusnya panik
/// panic!("Contoh ini menunjukkan kepanikan");
/// ```
///
/// ```compile_fail
/// // Kode ini seharusnya tidak dikompilasi
/// let x: i32 = "ini seharusnya tidak dikompilasi";
/// ```
///
/// ```no_run
/// // Kode ini dikompilasi tetapi tidak dijalankan
/// loop {
///     println!("Ini akan berjalan selamanya!");
/// }
/// ```
///
/// ```edition2021
/// // Kode ini menggunakan fitur Rust 2021
/// let result = try {
///     "10".parse::<i32>()?
/// };
/// ```

Menggunakan `?` dalam Pengujian Dokumen

Karena contoh dokumentasi dibungkus dalam fungsi main() yang mengembalikan (), menggunakan operator ? memerlukan penanganan khusus. Ada dua pendekatan:

Secara eksplisit definisikan fungsi main yang mengembalikan Result:

/// ```
/// # fn main() -> Result<(), std::io::Error> {
/// let content = std::fs::read_to_string("file.txt")?;
/// println!("Isi file: {}", content);
/// # Ok(())
/// # }
/// ```

2. Gunakan anotasi tipe dengan Ok(()):

/// ```
/// let content = std::fs::read_to_string("file.txt")?;
/// println!("Isi file: {}", content);
/// # Ok::<(), std::io::Error>(())
/// ```

Dalam kedua kasus, # di awal beberapa baris menyembunyikannya dari dokumentasi yang dirender tetapi menyertakannya dalam pengujian.

Menautkan ke Item dengan Nama

Rustdoc menyediakan sistem referensi silang yang kuat yang memungkinkan penulis dokumentasi untuk membuat tautan ke item lain dalam basis kode. Fitur ini secara signifikan meningkatkan kemampuan navigasi dokumentasi Anda.

Tautan Intra-dokumen

Untuk membuat tautan ke item lain, gunakan sintaks [nama_item]:

/// Menggunakan tipe [`HashMap`] dari pustaka standar.
///
/// Ini juga bergantung pada fungsi [`build_map`] yang didefinisikan di tempat lain dalam crate ini.
pub fn process_data() {
    // Implementasi
}

/// Membuat [`HashMap`] baru dengan nilai yang telah ditentukan sebelumnya.
pub fn build_map() -> HashMap<String, i32> {
    // Implementasi
}

Ketika Rustdoc memproses tautan ini, ia secara otomatis menyelesaikannya ke item yang benar, membuat hyperlink yang dapat diklik di HTML yang dihasilkan.

Kualifikasi Jalur

Untuk penautan yang lebih tepat, terutama ketika berhadapan dengan item yang mungkin memiliki nama yang sama di modul yang berbeda, Anda dapat menggunakan jalur yang sepenuhnya memenuhi syarat:

/// Fungsi ini menggunakan [`std::collections::HashMap`] untuk penyimpanan
/// dan [`crate::utils::format`] untuk memformat keluaran.
pub fn complex_operation() {
    // Implementasi
}

Resolusi jalur mengikuti aturan visibilitas Rust, jadi Anda hanya dapat menautkan ke item yang akan terlihat dari cakupan saat ini.

Target Tautan

Anda dapat menautkan ke berbagai jenis item:

/// Tautan ke struct: [`MyStruct`]
/// Tautan ke enum: [`Option`]
/// Tautan ke trait: [`Iterator`]
/// Tautan ke fungsi: [`process_data`]
/// Tautan ke metode: [`MyStruct::new`]
/// Tautan ke modul: [`crate::utils`]
/// Tautan ke konstanta: [`MAX_SIZE`]
/// Tautan ke alias tipe: [`Result`]

Sistem penautan yang komprehensif ini memungkinkan penulis dokumentasi untuk membuat jaringan dokumentasi yang saling berhubungan yang kaya yang membantu pengguna menavigasi API yang kompleks.

Fitur Dokumentasi Tingkat Lanjut

Atribut `#[doc]`

Atribut #[doc] menyediakan kontrol tingkat lanjut atas pembuatan dokumentasi:

// Setara dengan menggunakan komentar ///
#[doc = "Ini adalah dokumentasi untuk item di bawah ini."]
pub struct DocumentedStruct;

// Sembunyikan item dari dokumentasi
#[doc(hidden)]
pub struct InternalStruct;

// Tambahkan alias pencarian
#[doc(alias = "connection")]
#[doc(alias = "socket")]
pub struct NetworkStream;

Untuk dokumentasi bersyarat berdasarkan bendera fitur:

/// Fungsi ini melakukan hal-hal luar biasa.
#[doc = "Penjelasan kemampuan dasar."]
#[cfg_attr(feature = "advanced", doc = "Juga mendukung mode lanjutan ketika fitur 'advanced' diaktifkan.")]
pub fn do_things() {
    // Implementasi
}

Pola Sertakan Dokumentasi

Untuk menggunakan kembali konten di seluruh dokumentasi:

/// # Keamanan
///
#[doc = include_str!("../docs/common_safety_notes.md")]
pub unsafe fn perform_unsafe_operation() {
    // Implementasi
}

Ini memungkinkan Anda untuk memelihara segmen dokumentasi umum dalam file terpisah dan menyertakannya di mana diperlukan, mengurangi duplikasi dan memastikan konsistensi.

Contoh yang Dikikis

Rustdoc dapat secara otomatis mengekstrak contoh kode dari pengujian crate Anda dan direktori contoh, memberikan konteks tambahan untuk penggunaan API:

$ cargo doc --document-scraped-examples

Fitur ini berfungsi dengan memindai crate Anda untuk penggunaan item publik dan mengekstrak penggunaan tersebut sebagai contoh. Ini sangat berharga untuk API kompleks di mana contoh dokumentasi sebaris mungkin tidak mencukupi.

Dokumentasi Bersyarat

Menggunakan atribut cfg, Anda dapat secara bersyarat menyertakan atau mengecualikan dokumentasi:

#[cfg(target_os = "windows")]
/// Detail implementasi khusus Windows.
pub fn windows_only_function() {
    // Implementasi Windows
}

#[cfg(target_os = "linux")]
/// Detail implementasi khusus Linux.
pub fn linux_only_function() {
    // Implementasi Linux
}

Ini memungkinkan Anda untuk membuat dokumentasi khusus platform atau khusus fitur yang hanya muncul saat relevan.

HTML Kustom dalam Dokumentasi

Untuk kebutuhan pemformatan khusus, Rustdoc memungkinkan penyematan HTML langsung dalam dokumentasi:

/// <div class="warning">
/// <strong>Peringatan:</strong> Fungsi ini melakukan I/O dan mungkin memblokir.
/// </div>
pub fn blocking_operation() {
    // Implementasi
}

Dikombinasikan dengan CSS kustom, ini memungkinkan pemformatan yang kaya di luar apa yang disediakan Markdown saja.

HTML dan CSS Kustom

Rustdoc memungkinkan penyesuaian tampilan dokumentasi yang dihasilkan melalui HTML dan CSS:

Pra-pemrosesan HTML

Anda dapat menambahkan HTML kustom ke header dokumentasi:

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

Ini berguna untuk menambahkan stylesheet kustom, pustaka JavaScript, atau tag meta.

Penyesuaian CSS

Untuk menerapkan CSS kustom ke dokumentasi Anda:

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

File CSS Anda dapat menargetkan struktur HTML Rustdoc untuk menyesuaikan warna, font, tata letak, dan lainnya:

/* Ubah warna latar belakang utama */
body {
    background-color: #f5f5f5;
}

/* Gaya blok peringatan */
.warning {
    background-color: #fff3cd;
    border-left: 4px solid #ffc107;
    padding: 0.5rem 1rem;
    margin: 1rem 0;
}

/* Gaya kustom untuk blok kode */
pre {
    background-color: #282c34;
    border-radius: 6px;
    padding: 1rem;
}

Tema Rendering Kustom

Rustdoc mendukung beberapa tema bawaan, termasuk Light, Rust, Coal, Navy, dan Ayu. Anda juga dapat membuat tema kustom:

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

Praktik Terbaik Dokumentasi

Akurasi Teknis

Dokumentasi harus tepat secara teknis. Tentukan perilaku yang tepat, kasus tepi, dan karakteristik kinerja:

/// Mencari elemen dalam slice yang diurutkan menggunakan pencarian biner.
///
/// # Kompleksitas
///
/// Kompleksitas waktu: O(log n)
/// Kompleksitas ruang: O(1)
///
/// # Panik
///
/// Panik jika slice tidak diurutkan dalam urutan menaik.
///
/// # Contoh
///
/// ```
/// 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> {
    // Implementasi
}

Dokumentasi Terstruktur

Ikuti struktur yang konsisten untuk setiap jenis item:

Fungsi dan metode:

Deskripsi singkat
Penjelasan parameter
Deskripsi nilai kembalian
Kasus kesalahan
Bagian panik (jika berlaku)
Contoh
Karakteristik kinerja
Pertimbangan keamanan (untuk fungsi unsafe)

Struct dan enum:

Tujuan dan deskripsi tingkat tinggi
Penjelasan bidang/varian
Metode konstruksi
Operasi umum
Contoh penggunaan tipikal

Trait:

Kontrak dan jaminan
Penjelasan metode yang diperlukan
Dokumentasi metode yang disediakan
Panduan implementasi
Contoh yang menunjukkan implementasi dan penggunaan

Ketepatan Bahasa

Gunakan bahasa teknis yang tepat dan hindari ambiguitas:

Alih-alih "cepat," tentukan "kompleksitas waktu O(log n)"
Alih-alih "efisien memori," tentukan "menggunakan ruang tumpukan konstan"
Alih-alih "mungkin gagal," tentukan kondisi kesalahan yang tepat
Alih-alih "input besar," tentukan batasan konkret

Informasi Versi

Dokumentasikan stabilitas API dan pertimbangan versi:

/// Memproses paket jaringan sesuai dengan RFC 1234.
///
/// # Stabilitas
///
/// Fungsi ini dianggap stabil sejak versi 0.2.0.
///
/// # Perbedaan Versi
///
/// Sebelum 0.3.0, fungsi ini akan memotong paket secara diam-diam
/// lebih besar dari 1500 byte. Sekarang ia mengembalikan kesalahan.
pub fn process_packet(packet: &[u8]) -> Result<ProcessedPacket, PacketError> {
    // Implementasi
}

Teknik Pengujian Tingkat Lanjut

Pengujian di Lingkungan yang Berbeda

Anda dapat mengonfigurasi pengujian dokumentasi untuk dijalankan dengan variabel lingkungan tertentu:

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

Pengujian dengan Sumber Daya Eksternal

Untuk pengujian yang membutuhkan sumber daya eksternal, gunakan atribut no_run dan jelaskan persyaratannya:

/// ```no_run
/// // Contoh ini membutuhkan database PostgreSQL di localhost:5432
/// // dengan nama pengguna "test" dan kata sandi "test"
/// let db = my_crate::Database::connect(
///     "postgres://test:test@localhost:5432/testdb"
/// )?;
/// # Ok::<(), my_crate::Error>(())
/// ```

Pengujian Penanganan Kesalahan

Tunjukkan bagaimana kesalahan ditangani di API Anda:

/// ```
/// use my_crate::{process_data, DataError};
///
/// // Kasus berhasil
/// let result = process_data(&[1, 2, 3]);
/// assert!(result.is_ok());
///
/// // Kasus kesalahan
/// let error_result = process_data(&[]);
/// assert!(matches!(error_result, Err(DataError::EmptyInput)));
/// ```