توثيق Swift: كيفية الكتابة بوضوح وفعالية

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

مقدمة: لماذا توثيق مشروع Swift ضرورة

في عالم تطوير iOS و macOS، غالبًا ما يصبح التوثيق عالي الجودة هو العامل الذي يفصل بين المشروع الهاوي والمنتج الاحترافي. يهمل العديد من مطوري Swift توثيق الكود، معتمدين على بناء الجملة "الموثق ذاتيًا". ومع ذلك، عندما ينمو المشروع ليصل إلى عشرات الآلاف من الأسطر، وينضم أعضاء جدد إلى الفريق، يتحول غياب التوثيق الواضح إلى مشكلة خطيرة.

تشجع Apple بنشاط ثقافة التوثيق: بدءًا من Xcode 13، أصبحت أداة DocC (Documentation Compiler) المعيار الفعلي. تتيح لك إنشاء توثيق غني وتفاعلي مباشرة من الكود المصدري. في هذه المقالة، سنشرح كيفية كتابة التوثيق بشكل صحيح لمشاريع Swift — من التعليقات البسيطة إلى الأدلة المرجعية الكاملة.

أساسيات التوثيق: من التعليقات إلى DocC

تنسيق التوثيق في Swift

يدعم Swift تنسيقين رئيسيين للتعليقات: أحادي السطر (//) ومتعدد الأسطر (/* */). للتوثيق، يُستخدم بناء جملة Markdown الموسع، الذي يبدأ بـ /// (للتعليقات أحادية السطر) أو /** */ (للتعليقات متعددة الأسطر).

مثال أساسي لتوثيق دالة:

/// يحسب مضروب العدد.
///
/// تستخدم هذه الدالة نهجًا تكراريًا لحساب المضروب.
/// - Parameter n: عدد صحيح غير سالب.
/// - Returns: مضروب العدد n.
/// - Warning: لا تتعامل الدالة مع الأعداد السالبة.
func factorial(_ n: Int) -> Int {
    guard n >= 0 else { return 0 }
    return n == 0 ? 1 : n * factorial(n - 1)
}

العناصر الأساسية للتوثيق

عند كتابة التوثيق لـ Swift، استخدم الكلمات المفتاحية التالية (المعلمات):

- Parameter — وصف معامل الدالة
- Returns — وصف القيمة المُرجعة
- Throws — وصف الأخطاء المحتملة
- Warning — تحذيرات مهمة
- Note — ملاحظات إضافية
- Precondition — الشروط المسبقة للاستدعاء
- Complexity — تقدير تعقيد الخوارزمية

DocC: إنشاء توثيق احترافي

ما هو DocC؟

DocC (Documentation Compiler) هي أداة من Apple تقوم بتجميع التوثيق من الكود المصدري لـ Swift إلى موقع HTML ثابت. يدعم:

التوليد التلقائي للتوثيق لجميع الأنواع public و open
ربط المقالات والأدلة ومراجع API
تضمين الصور والرسوم البيانية وأمثلة الكود
عناصر تفاعلية: روابط لأجزاء أخرى من التوثيق

إعداد DocC في المشروع

لتفعيل DocC، يكفي إضافة مجلد Documentation.docc إلى المشروع. يتم إنشاء ملفات بامتداد .md بداخله. الهيكل الأساسي:

MyProject/
├── Sources/
│   └── MyProject/
│       └── MyClass.swift
└── Documentation.docc/
    ├── MyProject.md
    └── Articles/
        └── GettingStarted.md

مثال توثيق لفئة SwiftUI

/// عرض لعرض ملف تعريف المستخدم.
///
/// استخدم هذا المكون لعرض الصورة الرمزية والاسم والمعلومات المختصرة.
/// ```swift
/// UserProfileView(userName: "Анна", avatar: "person.circle.fill")
/// ```
public struct UserProfileView: View {
    let userName: String
    let avatar: String
    
    public var body: some View {
        HStack {
            Image(systemName: avatar)
                .resizable()
                .frame(width: 50, height: 50)
            Text(userName)
                .font(.title2)
        }
    }
}