Mendokumentasikan API untuk Kedua Tim

Pengembang Android dan iOS sama-sama memanggil kode bersama Anda, jadi dokumentasi yang jelas sama pentingnya dengan fungsi itu sendiri. 📝

KDoc adalah komentar dokumentasi Kotlin. Anda menulisnya tepat di atas deklarasi, lalu alat bantu mengubahnya menjadi halaman referensi yang mudah dibaca.

Kode menunjukkan apa yang terjadi; dokumentasi yang baik menjelaskan alasannya dan cara penggunaan yang dimaksud. Nyatakan hal yang dapat diharapkan pemanggil, bukan cara kerjanya di dalam.

Gunakan tag @param untuk menjelaskan setiap input. Pemanggil dari kedua aplikasi pun tahu persis apa yang harus diteruskan tanpa membaca kode sumber.

Tag @return menjelaskan apa yang dikembalikan. Catatan kembalian yang jelas mencegah asumsi keliru tentang satuan, rentang, atau null.

Bungkus nama dengan kurung siku untuk membuat tautan, seperti [Quote]. Pembaca dapat langsung menuju tipe terkait dalam dokumentasi yang dihasilkan.

Sebuah contoh kecil lebih baik daripada paragraf penjelasan. Satu cuplikan yang menunjukkan pemanggilan nyata dapat menjawab sebagian besar pertanyaan sebelum diajukan.

Curahkan usaha Anda pada permukaan publik. Pembantu internal cukup diberi komentar seperlunya karena tidak akan dipanggil oleh tim luar.

Pengembang Swift juga membaca KDoc Anda, jadi jelaskan perilakunya dengan istilah sederhana. Hindari jargon JVM yang tidak berarti di sisi iOS.

Dokka membaca KDoc Anda dan menghasilkan situs yang dapat dijelajahi. Kedua tim memperoleh satu referensi bersama, bukan menebak-nebak dari kode.

Dokumentasi yang sudah usang lebih menyesatkan daripada tidak ada dokumentasi. Perbarui KDoc dalam perubahan yang sama dengan kode agar keduanya tidak pernah menyimpang.

Tulis KDoc untuk API publik Anda, jelaskan alasannya, beri tag pada parameter dan nilai kembalian, tambahkan contoh, lalu biarkan Dokka membagikannya kepada kedua tim. 🎉