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

لماذا تحتاج إلى توثيق عالي الجودة لمشروع C#؟

التوثيق هو الجسر بين المطور ومستخدم الكود الخاص بك. في عالم C# (.NET)، يُبنى هذا الجسر باستخدام تعليقات XML والأدوات المتخصصة (DocFX، Sandcastle). التوثيق الجيد:

• يسرّع عملية إدخال مطورين جدد إلى المشروع
• يقلل من عدد الأسئلة في الدردشات والتذاكر
• يحسّن جودة الكود (ستقوم بشكل لا إرادي بإعادة هيكلة الطرق السيئة عند كتابة التوثيق لها)
• يُنشئ تلقائيًا مرجع API (IntelliSense في Visual Studio)

في هذه المقالة، سنستعرض الدورة الكاملة: من إعداد المشروع إلى نشر التوثيق على موقع ثابت. جميع الأمثلة بلغة C# (.NET 8).

1. تعليقات XML: أساس التوثيق في C#

1.1. كيفية تفعيل إنشاء ملف XML

يقوم Visual Studio (أو Rider) تلقائيًا بإنشاء ملف XML مع التعليقات، إذا قمت بتفعيل الخيار المناسب في .csproj:

<PropertyGroup>    <GenerateDocumentationFile>true</GenerateDocumentationFile>    <DocumentationFile>bin\\$(Configuration)\\$(TargetFramework)\\$(AssemblyName).xml</DocumentationFile></PropertyGroup>

بعد البناء، سيظهر ملف XML يحتوي على تعليقاتك في المجلد bin/Debug/net8.0/. هذا الملف هو المادة الخام لـ DocFX و Sandcastle.

1.2. وسوم XML الأساسية

لاستخدام كتابة توثيق مشروع C#، استخدم الوسوم التالية:

• <summary> — وصف مختصر للصنف، الطريقة، الخاصية.
• <param name="..."> — وصف معامل الطريقة.
• <returns> — وصف القيمة المُعادة.
• <exception cref="..."> — الاستثناءات التي قد تطرحها الطريقة.
• <example> — مثال على الاستخدام.
• <see cref="..."> — رابط إلى نوع أو طريقة أخرى.
• <code> — كود منسق داخل الوصف.

1.3. مثال على تعليق كامل

/// <summary>/// يقوم بإجراء قسمة آمنة لعددين مع التحقق من الصفر./// </summary>/// <param name="dividend">المقسوم (البسط).</param>/// <param name="divisor">المقسوم عليه (المقام). لا يمكن أن يساوي 0.</param>/// <returns>نتيجة القسمة في شكل كسر عشري.</returns>/// <exception cref="DivideByZeroException">يُطرح إذا كان divisor يساوي 0.</exception>/// <example>/// <code>/// double result = SafeDivider.Divide(10, 3);/// Console.WriteLine(result); // 3.333.../// </code>/// </example>public static double Divide(double dividend, double divisor){    if (divisor == 0)        throw new DivideByZeroException("القسمة على صفر غير مسموح بها.");    return dividend / divisor;}

نصيحة: اكتب التعليقات باللغة العربية إذا كان المشروع داخليًا، أو بالإنجليزية لواجهة برمجة تطبيقات مفتوحة. الأهم هو الالتزام بأسلوب موحد.

2. أدوات إنشاء التوثيق: DocFX مقابل Sandcastle

2.1. DocFX (موصى به)

DocFX هي أداة حديثة من Microsoft، تقوم من تعليقات XML وملفات Markdown الإضافية بإنشاء موقع ثابت. تدعم C# و VB.NET وحتى JavaScript.

التثبيت:

dotnet tool install -g docfx

البدء السريع:

docfx init -o my-docscd my-docsdocfx builddocfx serve _site

يقوم DocFX تلقائيًا بـ:

• مسح ملفات .csproj و .sln الخاصة بك
• استخراج تعليقات XML
• إنشاء صفحات لكل صنف، طريقة، خاصية
• إضافة التنقل، البحث، والسمات الجميلة (الافتراضي هو Bootstrap)