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

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

التوثيق عالي الجودة هو مفتاح نجاح مشروع C# وقابليته للصيانة. فهو يساعد المطورين على فهم الكود بسرعة، ويسهل عملية دمج أعضاء الفريق الجدد، ويقلل من عدد الأخطاء. في هذه المقالة، سنستعرض العملية الكاملة لإنشاء توثيق لمشروع C# (.NET): من أساسيات تعليقات XML إلى التوليد التلقائي لمواقع جميلة.

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

الطريقة القياسية لتوثيق الكود في C# هي تعليقات XML. تُكتب قبل تعريف الفئة، أو الدالة، أو الخاصية، أو أي عنصر آخر، وتبدأ بثلاث شرطات مائلة ///. يتعرف مترجم C# على هذه التعليقات ويمكنه إنشاء ملف XML للتوثيق.

فيما يلي الوسوم الأساسية التي ستستخدمها غالبًا:

\n
• <summary> — وصف مختصر للعنصر.
\n
• <param name="الاسم"> — وصف معامل الدالة.
\n
• <returns> — وصف القيمة المُرجعة.
\n
• <exception cref="النوع"> — وصف الاستثناء الذي قد ترميه الدالة.
\n
• <example> — مثال على الاستخدام.
\n
• <remarks> — ملاحظات إضافية.
\n

مثال على تعليق XML صحيح لدالة:

/// <summary>\n/// يحسب مضروب عدد صحيح غير سالب.\n/// </summary>\n/// <param name="n">عدد صحيح غير سالب.</param>\n/// <returns>مضروب العدد n.</returns>\n/// <exception cref="System.ArgumentException">يُرمى إذا كان n أقل من 0.</exception>\n/// <example>\n/// <code>\n/// int result = Factorial(5);\n/// // result يساوي 120\n/// </code>\n/// </example>\npublic static int Factorial(int n)\n{\n    if (n < 0)\n        throw new ArgumentException("n لا يمكن أن يكون سالبًا", nameof(n));\n\n    int result = 1;\n    for (int i = 1; i <= n; i++)\n    {\n        result *= i;\n    }\n    return result;\n}

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

لا تنسَ توثيق ليس فقط الدوال، بل أيضًا الفئات نفسها، بالإضافة إلى خصائصها وحقولها. هذا مهم بشكل خاص لواجهات برمجة التطبيقات العامة (APIs) التي سيستخدمها مطورون آخرون.

بالنسبة للخصائص، استخدم الوسوم <summary> و <value> (لوصف القيمة المخزنة):

/// <summary>\n/// يمثل مستخدمًا في النظام.\n/// </summary>\npublic class User\n{\n    /// <summary>\n    /// المعرف الفريد للمستخدم.\n    /// </value>\n    public int Id { get; set; }\n\n    /// <summary>\n    /// الاسم الكامل للمستخدم.\n    /// </summary>\n    /// <value>سلسلة نصية تحتوي على الاسم الأول والأخير.</value>\n    public string FullName { get; set; }\n\n    /// <summary>\n    /// ينشئ مستخدمًا جديدًا.\n    /// </summary>\n    /// <param name="id">المعرف.</param>\n    /// <param name="fullName">الاسم الكامل.</param>\n    public User(int id, string fullName)\n    {\n        Id = id;\n        FullName = fullName ?? throw new ArgumentNullException(nameof(fullName));\n    }\n}

3. توليد ملف XML وبناء التوثيق

للحصول على ملف XML من تعليقاتك، تحتاج إلى ضبط المشروع. في Visual Studio أو من خلال ملف .csproj، أضف:

<PropertyGroup>\n  <GenerateDocumentationFile>true</GenerateDocumentationFile>\n  <DocumentationFile>bin\\$(Configuration)\\$(TargetFramework)\\$(AssemblyName).xml</DocumentationFile>\n  <NoWarn>$(NoWarn);1591</NoWarn> <!-- يلغي التحذير الخاص بالتعليقات المفقودة إذا لزم الأمر -->\n</PropertyGroup>

بعد بناء المشروع، ستحصل على ملف XML يمكن استخدامه لإنشاء