كتابة توثيق لمشروع Kotlin: من الألف إلى الياء

تعلم Python بسهولة دون إرهاق نظري. حل مهام عملية مع التحقق التلقائي واكتب الكود مباشرة في المتصفح.

مقدمة: لماذا التوثيق مهم لمشروع Kotlin

\n\n

كتابة التوثيق ليست مجرد إجراء شكلي، بل هي عنصر أساسي لنجاح مشروع Kotlin. الكود الموثق جيدًا يسرّع عملية دمج المطورين الجدد، ويبسّط الصيانة، ويقلل من عدد الأخطاء. Kotlin، كونه لغة حديثة، يقدم أدوات قوية لإنشاء التوثيق: KDoc (المماثل لـ JavaDoc) وDokka (مولّد التوثيق). في هذه المقالة، سنستعرض الدورة الكاملة لكتابة التوثيق لمشروع Kotlin: من التعليقات في الكود إلى نشر التوثيق الجاهز.

\n\n

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

\n\n

أساسيات KDoc: الصياغة والهيكل

\n\n

KDoc هي لغة ترميز لتوثيق كود Kotlin. وهي مبنية على JavaDoc، لكنها مُكيَّفة مع خصائص Kotlin: الأمان من القيم الخالية (null-safety)، دوال الإضافة (extension functions)، الخصائص (properties)، والدوال اللامدا (lambdas). تبدأ تعليقات KDoc بـ /** وتنتهي بـ */.

\n\n

الهيكل الأساسي لتعليق KDoc

\n\n

يتكون كل تعليق KDoc من وصف ووسوم اختيارية. الوسوم الأساسية:

\n\n

@param — وصف معامل الدالة
@return — وصف القيمة المُعادة
@throws أو @exception — وصف الاستثناء
@see — رابط لعنصر آخر
@sample — إدراج مثال كود
@property — وصف خاصية الفئة
@constructor — وصف المُنشئ
@receiver — وصف المُستقبل لدوال الإضافة

\n\n

مثال على تعليق KDoc بسيط:

\n\n

/**\n * يحسب مضروب عدد معين.\n *\n * يستخدم نهجًا تكراريًا لتجنب تجاوز سعة المكدس.\n * يعمل فقط مع الأعداد الصحيحة غير السالبة.\n *\n * @param n عدد صحيح غير سالب لحساب مضروبه\n * @return مضروب العدد n (n!)\n * @throws IllegalArgumentException إذا كان n < 0\n */\nfun factorial(n: Int): Long {\n    require(n >= 0) { "n must be non-negative" }\n    var result = 1L\n    for (i in 2..n) {\n        result *= i\n    }\n    return result\n}

\n\n

توثيق الخصائص والفئات

\n\n

بالنسبة للفئات والخصائص، استخدم الوسم @property:

\n\n

/**\n * يمثل مستخدمًا في النظام.\n *\n * @property id المعرف الفريد للمستخدم\n * @property name الاسم الكامل للمستخدم\n * @property email عنوان البريد الإلكتروني\n * @property isActive علامة نشاط الحساب\n */\ndata class User(\n    val id: Long,\n    val name: String,\n    val email: String,\n    val isActive: Boolean = true\n)

\n\n

توليد التوثيق باستخدام Dokka

\n\n

Dokka هي الأداة الرسمية لتوليد توثيق Kotlin. وهي تدعم عدة صيغ للإخراج: HTML، Markdown، Javadoc وJSON. Dokka قادرة على معالجة المشاريع متعددة المنصات (multiplatform) وتعرض بشكل صحيح الهياكل الخاصة بـ Kotlin.

\n\n

إعداد Dokka في Gradle

\n\n

لإضافة Dokka إلى المشروع، قم بتوصيل الإضافة (plugin) في ملف build.gradle.kts:

\n\n

plugins {\n    id("org.jetbrains.dokka") version "1.9.20"\n}\n\ntasks.dokkaHtml {\n    outputDirectory.set(buildDir.resolve("dokka"))\n    moduleName.set("My Kotlin Library")\n}\n\ntasks.dokkaJavadoc {\n    outputDirectory.set(buildDir.resolve("javadoc"))\n}

\n\n

بعد ذلك، قم بتنفيذ الأمر ./gradlew dokkaHtml — سيتم توليد التوثيق في المجلد build/dokka.

\n\n