Documentation Comments

Komentar biasa membantu pembaca kode, namun library publik membutuhkan dokumentasi API yang terstruktur dan dapat dipublikasikan. Pada chapter ini kita akan membedah KDoc — format komentar dokumentasi resmi Kotlin — beserta tag pentingnya: @param, @return, @throws, dan @sample. Kita juga akan melihat bagaimana alat Dokka mengubah KDoc menjadi dokumentasi HTML yang dapat dijelajah.

Anatomi Blok KDoc #

Blok KDoc dibungkus /** */ dengan tanda bintang di awal setiap baris. Baris pertama biasanya berisi ringkasan satu kalimat, diikuti paragraf detail, lalu tag:

// File ini dikelompokkan dalam package "documentation" agar tag
// @sample dapat merujuk HitungDiskonContoh.contohPenggunaan dengan
// fully qualified name.
package documentation

/**
 * Menghitung diskon harga berdasarkan persentase.
 *
 * Function ini menerima harga awal dan persentase diskon, lalu
 * mengembalikan harga akhir setelah diskon diterapkan. Persentase
 * dinyatakan dalam rentang 0..100.
 *
 * Contoh penggunaan:
 * ```kotlin
 * val akhir = hitungDiskon(harga = 100_000, persen = 10)
 * // akhir == 90_000
 * ```
 *
 * @param harga harga awal sebelum diskon, harus bilangan non-negatif.
 * @param persen persentase diskon (0..100). Nilai di luar rentang
 *               akan memicu [IllegalArgumentException].
 * @return harga akhir setelah diskon diterapkan, sebagai [Int].
 * @throws IllegalArgumentException bila [persen] berada di luar 0..100
 *         atau [harga] bernilai negatif.
 * @sample documentation.HitungDiskonContoh.contohPenggunaan
 */
fun hitungDiskon(harga: Int, persen: Int): Int {
    require(harga >= 0) { "harga tidak boleh negatif: $harga" }
    require(persen in 0..100) { "persen harus di 0..100: $persen" }
    val potongan = harga * persen / 100
    return harga - potongan
}

object HitungDiskonContoh {
    fun contohPenggunaan() {
        val akhir = hitungDiskon(harga = 100_000, persen = 10)
        println("Harga akhir: $akhir")
    }
}

fun main() {
    HitungDiskonContoh.contohPenggunaan()
    println("Diskon 25% dari 80.000 = ${hitungDiskon(80_000, 25)}")
}

Output yang Dihasilkan:

Harga akhir: 90000
Diskon 25% dari 80.000 = 60000

Mari kita bedah bagian-bagian KDoc di atas:

1. Baris ringkasan (Menghitung diskon harga berdasarkan persentase.) — kalimat pertama yang akan muncul di daftar ringkasan Dokka. Usahakan satu kalimat, diakhiri titik.
2. Paragraf detail — penjelasan lebih lengkap, dipisahkan oleh baris kosong dari ringkasan. Dokka merender paragraf terpisah.
3. Blok kode — kotlin … di dalam KDoc akan dirender sebagai cuplikan kode pada dokumentasi. Bahasa dapat berupa kotlin, java, atau text.
4. Tag @param — mendokumentasikan parameter. Format: @param nama deskripsi.
5. Tag @return — mendokumentasikan nilai kembali.
6. Tag @throws — mendokumentasikan exception yang mungkin dilempar.
7. Tag @sample — menyisipkan isi function lain sebagai contoh kode pada dokumentasi.
8. Tautan referensi ([IllegalArgumentException], [harga], [persen]) — KDoc akan mengubahnya menjadi tautan ke simbol terkait pada dokumentasi HTML.

Tag Utama KDoc #

Berikut tag yang paling sering dipakai pada KDoc:

Tag KDoc mirip Javadoc, namun KDoc memakai Markdown untuk format teks alih-alih HTML. Kita dapat memakai heading, daftar, blok kode, dan penekanan gaya Markdown di dalam KDoc.

Tag @sample untuk Contoh Nyata #

Tag @sample sangat berguna ketika kita ingin dokumentasi API memuat contoh kode yang benar-benar berjalan — bukan hanya cuplikan statis. Cara kerjanya:

1. Kita tulis function contoh pada file Kotlin terpisah atau di modul sample.
2. Pada KDoc, kita rujuk function tersebut dengan fully qualified name.
3. Saat Dokka memproses, isi body function tersebut disisipkan sebagai blok kode pada dokumentasi.

package documentation

object HitungDiskonContoh {
    fun contohPenggunaan() {
        val akhir = hitungDiskon(harga = 100_000, persen = 10)
        println("Harga akhir: $akhir")
    }
}

Pada KDoc, kita rujuk sebagai @sample documentation.HitungDiskonContoh.contohPenggunaan. Karena function contohPenggunaan benar-benar dapat dijalankan, contoh pada dokumentasi selalu sinkron dengan API terbaru — bila signature berubah, kompilator akan menandai kesalahan.

Cara Dokka Merender KDoc #

Dokka adalah alat dokumentasi resmi Kotlin yang mengurai KDoc dan menghasilkan dokumentasi HTML. Output Dokka menampilkan:

• Ringkasan satu kalimat pada daftar anggota class.
• Halaman detail per function, class, dan property.
• Tautan silang otomatis dari [NamaSimbol] ke halaman simbol tersebut.
• Contoh kode dari @sample sebagai blok sintaks yang disorot.
• Daftar parameter, exception, dan nilai kembali pada tabel terpisah.

Perintah dasar Dokka dari Gradle:

./gradlew dokkaHtml

Output berada di build/dokka/html/ dan dapat dibuka langsung di browser atau dipublikasikan ke GitHub Pages.

Referensi Tautan dalam KDoc #

KDoc mengenali beberapa bentuk tautan:

/**
 * Lihat [HitungDiskon] untuk class terkait.
 * Untuk detail exception, baca [IllegalArgumentException].
 * Method ini memanggil [hitungDiskon] internal.
 */

• [HitungDiskon] — tautan ke class HitungDiskon di project yang sama.
• [IllegalArgumentException] — tautan ke class standard library Java (Dokka menautkan ke dokumentasi JDK).
• [hitungDiskon] — tautan ke function dalam class atau file yang sama.
• [package.name.Simbol] — tautan eksplisit dengan fully qualified name.

Referensi Lanjutan #

• Kotlin KDoc — panduan resmi KDoc untuk tag @param, @return, dan @throws pada komentar dokumentasi

KDoc menjadikan dokumentasi API bagian tak terpisahkan dari kode sumber. Dengan KDoc yang rapi, pengguna library kita dapat menjelajah API tanpa membuka kode. Setelah komentar dan dokumentasi tersusun, kita siap melihat satu ciri khas Kotlin: if, when, dan try sebagai expression yang menghasilkan nilai — pembahasan lengkap menanti pada chapter Statement dan Expression.