Dokka Kotlin: دليل شامل مع أمثلة وتثبيت

مقدمة عن Dokka: ما هي ولماذا تحتاجها

Dokka هي أداة قوية لإنشاء التوثيق من كود المصدر بلغة Kotlin. طورتها شركة JetBrains، وتعتبر الحل الرسمي لإنشاء توثيق مشاريع Kotlin. تقوم الأداة بتحليل الكود الخاص بك، واستخراج تعليقات KDoc (المكافئ لـ JavaDoc في Kotlin)، ثم إنشاء توثيق منظم بعدة صيغ: HTML، Markdown، Javadoc وغيرها.

لماذا تحتاج Dokka؟

أتمتة كاملة: لن تحتاج لكتابة التوثيق يدويًا. Dokka تنشئه تلقائيًا بناءً على الكود والتعليقات.
دقة وتحديث مستمر: التوثيق يظل متطابقًا مع الكود لأنه يُنشأ مباشرة منه.
دعم Kotlin Multiplatform: تعمل Dokka بكفاءة مع المشاريع متعددة المنصات، وتدمج التوثيق من وحدات مختلفة (common, jvm, js, native).
مرونة عالية: يمكنك تخصيص المظهر، صيغة الإخراج، وتضمين أو استبعاد أجزاء معينة من الكود.
تكامل سلس: تتكامل بسهولة مع أنظمة البناء Gradle و Maven.

لا غنى عن Dokka لمطوري المكتبات، واجهات API، والمشاريع الكبيرة حيث يكون التوثيق عالي الجودة أمرًا حاسمًا للمستخدمين.

تثبيت Dokka

لا يتم تثبيت Dokka عبر pip أو npm، لأنها أداة خاصة ببيئة Kotlin/JVM. الطريقة الأساسية للتثبيت هي عبر نظام البناء Gradle (موصى به) أو Maven.

التثبيت عبر Gradle (Kotlin DSL)


// build.gradle.kts
plugins {
    id("org.jetbrains.dokka") version "1.9.20" // تحقق من أحدث إصدار
}

// أو عبر apply plugin:
// apply(plugin = "org.jetbrains.dokka")

التثبيت عبر Gradle (Groovy DSL)


// build.gradle
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>compile</phase>
            <goals><goal>dokka</goal></goals>
        </execution>
    </executions>
</plugin>

بداية سريعة: التشغيل الأول

بعد إضافة الإضافة (plugin)، كل ما عليك هو كتابة بعض تعليقات KDoc في الكود وتشغيل مهمة Gradle.

الخطوة 1: اكتب الكود مع التعليقات


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

/**
 * آلة حاسبة بسيطة تقوم بالعمليات الحسابية الأساسية.
 *
 * @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 dividend المقسوم.
     * @param divisor المقسوم عليه. لا يمكن أن يساوي صفرًا.
     * @return ناتج القسمة.
     * @throws IllegalArgumentException إذا كان المقسوم عليه يساوي صفرًا.
     */
    fun divide(dividend: Double, divisor: Double): Double {
        if (divisor == 0.0) throw IllegalArgumentException("المقسوم عليه لا يمكن أن يكون صفرًا")
        return dividend / divisor
    }
}