AR
RU
EN
ES
ZH
FR
DE
PT
HI
مقدمة: لماذا التوثيق ليس ترفًا بل ضرورة
\n\nكل مطور C++ واجه مرة واحدة على الأقل موقفًا يتحول فيه كود شخص آخر (أو كوده الخاص) بعد شهر إلى غابة مظلمة. إن التعقيد العالي للغة، وكثرة القوالب، والمؤشرات الذكية، والوراثات تجعل مشاريع C++ عرضة بشكل خاص لغياب التوثيق. بدونه، يخاطر المشروع بأن يصبح "إرثًا" حتى قبل الإصدار الأول.
\n\nفي هذه المقالة، سنستعرض الدورة الكاملة لإنشاء التوثيق لمشروع C++: من اختيار الأدوات إلى النشر. ستتعلم كيف يمكنك باستخدام Doxygen و Markdown تحويل الكود الخام إلى نظام منظم وقابل للقراءة والصيانة.
\n\n1. التخطيط واختيار الأدوات
\n\n1.1. تحديد الجمهور والأهداف
\n\nقبل كتابة أول سطر، أجب على ثلاثة أسئلة:
\n- \n
- من سيقرأ التوثيق؟ (الزملاء، العملاء، مجتمع المصادر المفتوحة) \n
- ما هو مستوى إتقان C++ لدى القارئ؟ (مبتدئ، متوسط، خبير) \n
- ما الذي يجب توثيقه؟ (API العام فقط أم المنطق الداخلي) \n
بالنسبة لمشروع C++، تتضمن المجموعة القياسية:
\n- \n
- README.md — نقطة دخول للمطورين الجدد \n
- مرجع API — توثيق تم إنشاؤه تلقائيًا للفئات والوظائف \n
- دليل المستخدم — أمثلة على البناء والتكوين والاستخدام \n
- CHANGELOG — سجل الإصدارات \n
1.2. أدوات C++
\n\nالمعيار الفعلي هو Doxygen. وهو يدعم C++ و C و Python ولغات أخرى، ويولد HTML و LaTeX و PDF. البدائل:
\n- \n
- Sphinx مع Breathe — إذا كان المشروع يستخدم أغلفة Python \n
- MkDocs — لتوليد موقع سريع من Markdown \n
- Doxygen + Doxybook2 — نهج هجين \n
سنستخدم Doxygen لأنه الأكثر تكيفًا مع C++.
\n\n2. التعليق على الكود: القواعد والأمثلة
\n\n2.1. بناء جملة Doxygen الأساسي
\n\nيدعم Doxygen نمطين من التعليقات:
\n- \n
- نمط Javadoc —
/** ... */\n - نمط Qt —
/*! ... */\n
مثال لتوثيق فئة وطريقة:
\n\n/**\n * @brief مؤشر ذكي مع عد المرجع.\n *\n * ينفذ الوظائف الأساسية لـ std::shared_ptr.\n * غير آمن للاستخدام مع تعدد الخيوط.\n *\n * @tparam T نوع الكائن المخزن\n */\ntemplate <typename T>\nclass SharedPtr {\npublic:\n /**\n * @brief ينشئ مؤشرًا من كائن خام.\n * @param ptr مؤشر إلى كائن مخصص (يمكن أن يكون nullptr).\n * @warning بعد استدعاء هذه الدالة، تنتقل الملكية إلى SharedPtr.\n */\n explicit SharedPtr(T* ptr = nullptr);\n \n /**\n * @brief الحصول على عدد المراجع للكائن.\n * @return العدد الحالي للمالكين.\n */\n size_t use_count() const noexcept;\n};2.2. علامات Doxygen الأساسية
\n\nبالنسبة لمشاريع C++، استخدم بالتأكيد:
\n- \n
@brief— وصف مختصر (يظهر في القوائم) \n @param— وصف معاملات الدالة \n @return— القيمة المُعادة \n @throw/@exception— الاستثناءات \n @tparam— معاملات القالب \n @warning— تحذيرات مهمة \n @note— ملاحظات \n @see— روابط لفئات ذات صلة \n
2.3. توثيق التراكيب المعقدة في C++
\n\nانتبه بشكل خاص إلى:
\n- \n
- القوالب — اشرح الأنواع المتوقعة \n
- تحميل العوامل — صف الدلالات
