Kotlin-də kodun sənədləşdirilməsi üçün hansı…

Kotlin-də kodun sənədləşdirilməsi üçün JavaDoc sintaksisinə əsaslanan KDoc istifadə olunur.

KDoc-un əsas elementləri:

Sənədləşdirmə blokları: /** ilə başlayır və */ ilə bitir. Sənədləşdirmək istədiyiniz sinif, funksiya, xüsusiyyət və ya digər varlığın əvvəlində yerləşdirilir.
Təsviri: Sənədləşdirmə blokunun ilk sətiri qısa təsvir olur. Boş sətirdən sonra daha ətraflı təsvir gələnə bilər.
Etiketlər: Strukturlaşdırılmış məlumat təqdim etmək üçün istifadə olunur. Bəzi yaygın etiketlər:
- @param <parametr adı> <təsviri>: Funksiya və ya konstruktor parametrini təsvir edir.
- @return <təsviri>: Funksiyanın geri qaytardığı dəyəri təsvir edir.
- @constructor <təsviri>: Sinifin konstruktorunu təsvir edir.
- @throws <istisna tipi> <təsviri>: Atıla biləcək istisnayı təsvir edir.
- @sample <funksiyanın tam adı>: Sənədləşdirilmiş varlığın istifadə nümunəsini təqdim edir.
- @author <ad>: Kodun müəllifini göstərir.
- @since <sürüm>: Varlığın əlavə olunduğu versiyanı göstərir.
- @see <məqsəd>: Digər əlaqəli sənədləşdirmə elementinə istinad edir.

KDoc istifadəsi nümunəsi:

/**
 * Bu sinf istifadəçini təmsil edir.
 *
 * @property name İstifadəçinin adı.
 * @property age İstifadəçinin yaşı.
 */
class User(
    val name: String,
    val age: Int
) {

    /**
     * İstifadəçiyə salam verir.
     *
     * @param greeting Salam.
     * @return Salam və istifadəçinin adı ilə sətir.
     * @throws IllegalArgumentException Əgər salam boşdursa.
     */
    fun greet(greeting: String): String {
        if (greeting.isEmpty()) {
            throw IllegalArgumentException("Salam boş ola bilməz")
        }
        return "$greeting, $name!"
    }
}

Sənədləşdirmənin yaradılması:

KDoc-dan sənədləşdirmə yaratmaq üçün istifadə edilə bilər:

Dokka: Kotlin üçün rəsmi sənədləşdirmə vasitəsidir. Müxtəlif çıxış formatlarını dəstəkləyir (HTML, Markdown, JSON və digər) və qarışıq layihələr üçün sənədləşdirmə yarada bilər (Kotlin, Java, Scala). Gradle və Maven ilə inteqrasiya olunur.
IDE üçün plaginlər: IntelliJ IDEA və Android Studio KDoc üçün daxili dəstəyə malikdir və sənədləşdirməni pop-up pəncərələrdə göstərməyə və HTML sənədləşdirmə yaratmağa imkan verir (Dokka əsasında).

Əlavə imkanlar:

Markdown: KDoc blokları daxilində əsas Markdown sintaksisindən istifadə edilə bilər (qalın, italik, siyahılar, linklər).
Linklər: Digər sinflərə, funksiyalara və ya xüsusiyyətlərə [<məqsəd>] sintaksisi ilə linklər yaradıla bilər.

KDoc güclü bir vasitədir və Kotlin kodu üçün oxunaqlı və saxlanması asan sənədlər yaratmağa kömək edir. Onun müntəzəm istifadəsi komanda tərəfindən kodun anlaşılmasını yaxşılaşdırır və gələcək inkişafı asanlaşdırır.

Kotlin-də kodun sənədləşdirilməsi üçün hansı mexanizmlər mövcuddur?