1. ما هي Dokka ولماذا تحتاجها؟

Dokka هي محرك حديث لتوليد التوثيق للغة Kotlin، طورته شركة JetBrains. على عكس JavaDoc التقليدي، تفهم Dokka خصوصية Kotlin: الأمان من القيم الفارغة (null-safety)، دوال التوسيع (extension functions)، الخصائص، coroutines، الفئات المختومة (sealed classes) وغيرها من التراكيب الفريدة للغة. إذا كنت تكتب مكتبة أو API بلغة Kotlin، فإن Dokka تتيح لك إنشاء توثيق قابل للقراءة ومنظم تلقائيًا بصيغ HTML، Markdown، Javadoc أو حتى JSON لمزيد من المعالجة.

لماذا تحتاجها؟ أولاً، تبسط Dokka بشكل كبير صيانة التوثيق في المشاريع الكبيرة —只需 كتابة تعليقات KDoc (المشابهة لـ JavaDoc ولكن مع دعم Markdown) في الكود، وستقوم الأداة بإنشاء موقع جاهز. ثانيًا، تستطيع Dokka دمج التوثيق من عدة وحدات Gradle أو Maven في مشروع واحد، وهو أمر حيوي للمكتبات متعددة الوحدات. ثالثًا، تدعم Dokka التخصيص من خلال القوالب والإضافات، مما يسمح بتكييف المظهر مع الهوية المؤسسية.

تُستخدم Dokka بنشاط في التوثيق الرسمي لـ Kotlin (kotlinlang.org)، وفي مكتبات Ktor، Exposed، Kotlinx.serialization وغيرها الكثير. إنها المعيار الفعلي لتوثيق مشاريع Kotlin، وإذا كنت تريد أن تبدو مكتبتك احترافية — فإن Dokka أمر لا بد من تعلمه.

2. التثبيت

يتم توزيع Dokka كإضافة لأنظمة البناء Gradle و Maven. لا يوجد أمر منفصل مثل pip أو npm، لأنها أداة للنظام البيئي لـ JVM. فيما يلي التعليمات الدقيقة لـ Gradle (Kotlin DSL) — الطريقة الأكثر شيوعًا.

Gradle (Kotlin DSL) — إضافة لوحدة واحدة

أضف إلى ملف build.gradle.kts:

plugins {
    id("org.jetbrains.dokka") version "1.9.20"
}

dependencies {
    // التبعيات الخاصة بك
}

// الإعدادات الأساسية (اختياري)
tasks.withType<org.jetbrains.dokka.gradle.DokkaTask>() {
    outputDirectory.set(file("$buildDir/dokka"))
}

Gradle (Groovy DSL)

plugins {
    id "org.jetbrains.dokka" version "1.9.20"
}

Maven

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    <version>1.9.20</version>
    <executions>
        <execution>
            <phase>pre-site</phase>
            <goals>
                <goal>dokka</goal>
            </goals>
        </execution>
    </executions>
</plugin>

بعد الإعداد، قم بتشغيل الأمر:

./gradlew dokkaHtml       # لـ HTML
./gradlew dokkaGfm        # لـ Markdown (GFM)
./gradlew dokkaJavadoc    # لنمط Javadoc

3. البداية السريعة — مثال عملي بسيط

أنشئ ملف Kotlin بسيطًا مع تعليقات KDoc:

// src/main/kotlin/com/example/Calculator.kt
package com.example

/**
 * آلة حاسبة بسيطة، توضح عمل Dokka.
 *
 * @author فريق PythonLib
 * @since 1.0.0
 */
class Calculator {

    /**
     * يجمع عددين.
     *
     * @param a العدد الأول
     * @param b العدد الثاني
     * @return مجموع a و b
     */
    fun add(a: Int, b: Int): Int = a + b

    /**
     * يقسم عددًا على آخر.
     *
     * @param a المقسوم
     * @param b المقسوم عليه (لا يمكن أن يكون صفرًا)
     * @return نتيجة القسمة
     * @throws IllegalArgumentException إذا كان b == 0
     */
    fun divide(a: Double, b: Double): Double {
        require(b != 0.0) { "المقسوم عليه لا يمكن أن يكون صفرًا" }
        return a / b
    }
}

قم بتشغيل ./gradlew dokkaHtml. في المجلد build/dokka ستجد التوثيق الذي تم إنشاؤه.