Komentar dan Dokumentasi

Topik ini membahas tiga lapis anotasi pada kode Rust: komentar biasa yang diabaikan compiler, komentar dokumentasi yang diolah rustdoc menjadi halaman referensi, serta penataan contoh di dalam dokumentasi. Setelah membacanya, pembaca dapat menandai bagian kode dengan komentar yang tepat dan membangun dokumentasi HTML dari proyek sendiri dengan cargo doc.

Komentar biasa#

Komentar biasa diawali dua garis miring dan berlanjut sampai akhir baris. Compiler mengabaikan seluruh isinya, sehingga komentar berfungsi menjelaskan maksud kode bagi pembaca manusia.

fn main() {
    // catatan suhu harian sensor ruang kerja
    let suhu = 36.5; // masih dalam batas normal

    // konversi ke satuan Fahrenheit
    let fahrenheit = suhu * 9.0 / 5.0 + 32.0;
    println!("suhu: {suhu} C = {fahrenheit} F");
}

suhu: 36.5 C = 97.7 F

Komentar boleh berdiri sendiri pada satu baris maupun menempel di akhir baris kode. Rust juga menyediakan komentar blok /* ... */ yang membungkus banyak baris sekaligus, tetapi kebiasaan komunitas memakai // karena setiap baris tetap mudah dibaca saat perubahan kode dibandingkan antar versi. Komentar blok Rust dapat bersarang, sehingga penulisan /* /* */ */ tetap dihitung sebagai satu komentar terluar dan sifat ini memudahkan penonaktifan sementara kode yang sudah berisi komentar blok lain. Komentar yang baik menjelaskan alasan di balik keputusan, misalnya mengapa konversi dilakukan dengan pembulatan tertentu, karena kode sendiri sudah menyatakan apa yang dilakukan. Komentar yang hanya mengulang isi kode, misalnya // tambahkan satu di atas baris hitung += 1;, tidak menambah informasi apa pun.

Komentar dokumentasi#

Komentar dokumentasi ditulis dengan tiga garis miring /// dan menempel pada item yang mengikutinya, seperti fungsi, struktur, atau modul. Isinya ditulis dalam format Markdown dan menjadi bagian dari dokumentasi publik sebuah crate. Bentuk sejenis dengan dua garis miring dan tanda seru //! berlaku untuk modul atau berkas secara keseluruhan dan diletakkan di awal berkas.

// tidak-dijalankan
/// Menghitung rata-rata dua nilai.
///
/// Nilai yang dikembalikan bertipe f64 sehingga hasilnya dapat berupa pecahan.
fn rata_rata(a: f64, b: f64) -> f64 {
    (a + b) / 2.0
}

Paragraf pertama menjadi ringkasan singkat pada daftar fungsi, sedangkan paragraf berikutnya tampil di halaman detail. Judul tingkat satu seperti # Contoh lazim dipakai untuk memisahkan bagian contoh. Blok kode di dalamnya ditulis dengan pagar tiga seperti pada Markdown biasa.

Ketiga bentuk penanda memiliki peran yang tidak saling menggantikan. Komentar // ditujukan bagi penulis kode, sedangkan /// dan //! ditujukan bagi pengguna kode melalui halaman dokumentasi. Pemilihan yang tepat menentukan apakah sebuah penjelasan sampai kepada pembaca yang membutuhkannya.

Selain # Contoh, dokumentasi pustaka lazim memuat bagian baku lain. Bagian # Panics menyatakan kondisi yang membuat fungsi memicu panic, # Errors menjelaskan variasi error pada tipe kembalian Result, dan # Safety menjadi syarat pada fungsi bertanda unsafe. Compiler tidak mewajibkan bagian-bagian tersebut, tetapi konvensi ini dipakai luas di ekosistem Rust sehingga pembaca dokumentasi mencarinya di tempat yang sama pada setiap pustaka.

Proyek contoh catatan-suhu#

Pembangunan dokumentasi memerlukan proyek Cargo agar rustdoc mengetahui nama crate serta struktur modulnya. Buat proyek baru dengan cargo new catatan-suhu, lalu lengkapi dua berkasnya sehingga menjadi seperti berikut. Berkas Cargo.toml menyatakan identitas paket beserta edisi bahasanya, sedangkan seluruh kode program berada di src/main.rs yang dikenali Cargo sebagai program utuh.

[package]
name = "catatan-suhu"
version = "0.1.0"
edition = "2021"

//! Catatan suhu: program kecil untuk mengolah pembacaan sensor.

/// Mengonversi suhu dari Celsius ke Fahrenheit.
///
/// # Contoh
///
/// ```
/// let f = celsius_ke_fahrenheit(36.5);
/// assert!((f - 97.7).abs() < 0.001);
/// ```
fn celsius_ke_fahrenheit(celsius: f64) -> f64 {
    celsius * 9.0 / 5.0 + 32.0
}

fn main() {
    let suhu = 36.5;
    println!("{suhu} C sama dengan {:.1} F", celsius_ke_fahrenheit(suhu));
}

36.5 C sama dengan 97.7 F

Komentar //! di baris pertama mendokumentasikan berkas secara keseluruhan, sedangkan /// di depan celsius_ke_fahrenheit mendokumentasikan fungsi tersebut beserta contoh pemakaiannya. Penentu pemformatan {:.1} pada println! membatasi pecahan menjadi satu angka di belakang koma. Pada crate pustaka, blok contoh seperti ini dijalankan rustdoc sebagai pengujian saat cargo test dijalankan. Crate biner seperti proyek ini tidak menyediakan pustaka yang dapat ditautkan, sehingga contohnya tidak dieksekusi, dan pembahasan doc test secara rinci berada pada modul pengujian.

Membangun dokumentasi dengan cargo doc#

Perintah cargo doc memanggil rustdoc untuk mengubah seluruh komentar dokumentasi menjadi halaman HTML yang saling tertaut. Jalankan perintah berikut dari direktori akar proyek.

# bangun dokumentasi untuk proyek ini tanpa dependensi eksternal
cargo doc --quiet --no-deps

# lihat berkas dokumentasi yang dihasilkan
ls target/doc/catatan_suhu

all.html
fn.celsius_ke_fahrenheit.html
fn.main.html
index.html
sidebar-items.js

Opsi --no-deps membatasi pembangunan hanya pada crate proyek sendiri sehingga prosesnya cepat dan tidak memerlukan jaringan. Hasilnya berada di direktori target/doc, dan nama subdirektorinya mengikuti nama crate dengan tanda hubung yang diganti garis bawah, sehingga catatan-suhu menjadi catatan_suhu. Halaman utama crate tersimpan sebagai index.html dengan satu halaman per fungsi terdokumentasi. Buka halaman tersebut di browser untuk melihat ringkasan, penjelasan, serta contoh yang ditulis sebelumnya. Tanpa opsi --no-deps, rustdoc juga membangun dokumentasi seluruh dependensi sehingga halaman pustaka pihak ketiga ikut tersedia dan tertaut dari dokumentasi proyek.

# tidak-dijalankan
# buka dokumentasi langsung di browser (memerlukan antarmuka grafis)
cargo doc --open --no-deps

Perintah cargo doc --open menjalankan pembangunan yang sama lalu membuka halaman utama secara otomatis. Halaman yang dihasilkan bersifat statis sehingga dapat diunggah ke hosting apa pun tanpa proses tambahan, dan situs dokumentasi pustaka-pustaka publik umumnya dibangun dengan alur yang sama. Dokumentasi pustaka bawaan Rust dibangun dengan cara yang serupa dan dapat diakses di situs doc.rust-lang.org.

Kesalahan umum#

Memakai // untuk dokumentasi. Komentar dua garis miring sepenuhnya diabaikan rustdoc, sehingga halaman dokumentasi tetap kosong walaupun penjelasan sudah ditulis. Gunakan /// untuk item dan //! untuk modul atau berkas. Pindahkan penjelasan yang memuat contoh pemakaian ke salah satu bentuk tersebut supaya ikut dirender menjadi halaman HTML.

Menempatkan /// di depan pernyataan. Komentar /// hanya sah menempel pada item seperti fungsi. Penempatannya di depan pernyataan let di dalam fungsi menghasilkan peringatan unused doc comment karena rustdoc tidak membuat dokumentasi untuk pernyataan. Pindahkan komentar ke atas fungsi yang memuat pernyataan itu, atau ubah menjadi komentar biasa apabila penjelasannya memang ditujukan bagi penulis kode.

Ringkasan#

• Komentar biasa // diabaikan compiler dan berfungsi menjelaskan kode bagi manusia.
• Komentar /// mendokumentasikan item di bawahnya dalam format Markdown, sedangkan //! mendokumentasikan modul atau berkas.
• cargo doc --quiet --no-deps membangun halaman HTML ke direktori target/doc tanpa memproses dependensi.
• cargo doc --open membangun dokumentasi lalu membukanya di browser.
• Blok contoh pada komentar dokumentasi dijalankan sebagai pengujian oleh cargo test pada crate pustaka.

Referensi#

• Comments — The Rust Book — Bentuk komentar biasa dan komentar dokumentasi.
• Doc comments — Rust by Example — Contoh ///, //!, serta bagian yang didukungnya.
• The rustdoc book — Panduan lengkap pembangunan dokumentasi dengan rustdoc dan cargo doc.