تحتوي هذه الصفحة على تفاصيل مشروع كتابة تقنيّة تم قبوله في موسم المستندات من Google.
ملخص المشروع
- المؤسسة المفتوحة المصدر:
- ScummVM
- الكاتب التقني:
- b-gent
- اسم المشروع:
- تحسين مستندات رمز المصدر من خلال Doxygen
- مدة المشروع:
- المدة العادية (3 أشهر)
وصف المشروع
يتم نشر المستندات الحالية لواجهة برمجة تطبيقات ScummVM (رمز المصدر) هنا: https://doxygen.scummvm.org/modules.html.
وهو ينقصه للأسف في العديد من المجالات:
1) بدون هيكل عمليًا، وجميع المعلومات عائمة على المستوى ذاته.
2) تم توثيق عناصر C++ بشكل غير متناسق حيث إن بعضها غير موثق على الإطلاق. هذا شيء تذكره المؤسسة باعتباره إحدى المشكلات الرئيسية.
3) لا يزال يتم عرض المحتوى القديم والمتوقّف في الإخراج.
4) يجب جعل اللغة واستخدام وضع علامات الأكسجين أكثر اتساقًا. هناك حاجة إلى مجموعة من القواعد، وهو شيء يمكن أن يكون أساسًا لدليل نمط التوثيق المستقبلي لهذا المشروع.
5) يمكن تحسين لغة CSS المستخدمة في هذه الصفحة لجعلها أكثر تشابهًا مع موقع ScummVM على الويب: https://www.scummvm.org
يمكن معالجة كل هذه المشكلات أثناء مشروع "موسم المستندات".
يصاحب تطبيق Season of Docs هذا مسودة العلاقات العامة التي فتحتها في المشروع لتوضيح بعض التحسينات المحتملة التي أقترحها: https://github.com/scummvm/scummvm/pull/2361 يمكنك الاطلاع على الوصف هناك للحصول على بعض التفاصيل حول ما يحتوي عليه وعرض الفرق.
إليكم تقريبًا ما يتضمنه تقرير العلاقات العامة:
1) أعتقد أن أكثر ما يربك الآن للمساهمين المحتملين الجدد، وكل من يعرض مستند واجهة برمجة التطبيقات الحالي، هو الافتقار إلى البنية. يساعد تقديم مستندات واجهة برمجة التطبيقات المنظَّمة في تحسين قابلية القراءة والسهولة في العثور على مجموعة المستندات، وبالتالي سهولة استخدامها. ولهذا السبب، يُقدّم "قسم الرئيس" الخاص بي مجموعات Doxygen في جميع ملفات العنوان في المجلد "common" (عام). باستخدام هذه البنية الجديدة، إذا أراد أحد المستخدمين العثور على مستندات لواجهة برمجة التطبيقات المتعلقة بنظام التشغيل (على سبيل المثال)، يمكنه العثور عليها بسهولة في شريط التنقل.
2) تم إعداد ملف إعداد doxygen جديد لتفعيل إنشاء هذه المستندات.
3) ملف 'links.doxyfile' يمكن أن يكون من مصدر واحد لجميع الروابط المستخدمة في مجموعة المستندات. آلية مفيدة عند التعامل مع الأكسجين
4) لغة CSS معدّلة لـ doxygen هذا مأخوذ حاليًا من مشروع آخر مفتوح المصدر وهو فقط نقطة بداية. من الناحية المثالية، يجب أن يكون شكل ومظهر صفحة doxygen أكثر أو أقل اتساقًا مع صفحة ويب ScummVM.
المحتوى الذي لا يتناوله "PR" لا يغطّي ولكن يجب العمل عليه بالتأكيد. وأعني بذلك تحديد الأجزاء الأساسية من الرمز التي لم يتم توثيقها، أو تلك التي لم يتم توثيقها بشكل كافٍ، أو الأجزاء القديمة من الرمز التي يجب إزالتها من المستندات. بما أنني لم أعمل في المشروع من قبل، فستكون هناك حاجة إلى توجيه من مرشد لتحقيق ذلك.
وبالطبع، سواء نفذنا أي شيء من العلاقات العامة، عليك مناقشته مع المؤسسة. فكرت في أنّ الأفعال تخطو الكلمات، لذلك قرّرت عرض ما يمكنني فعله بدلاً من وصفه في التطبيق.
قدّمت المؤسسة الجدول الزمني التقريبي التالي لهذا المشروع: المهمة الرئيسية للأسبوع 1- الأسبوع 0 (قبل 9/14) مناقشة الاقتراح والمراجعات الأسبوع 1 (9/14) إعداد إنشاء Doxygen الأسبوع 2 (9/21) تحديث واجهة Doxygen (أولوية منخفضة) 1- الأسبوع 3 (9/28) الكود المشترك، الأسبوع 0 (9 / 28) رمز النموذج المشترك - O / 14 (العينة، الكود المشترك، الأسبوع، 1) رمز الحدث / الأسبوع 0، متابعة 5 - رمز الحدث، الأسبوع، المحرك، 1، .
التغيير الوحيد الذي أقترحه هو البدء بالعمل على الهيكل، كما ذكرنا سابقًا. ويمكن إجراء ذلك في الأسبوعَين الأول والثاني، بالإضافة إلى عملية إعداد تركيبة الدوكسجين (التي تم الانتهاء منها إلى حد كبير) وتحديث بشرة Doxygen. بعد ذلك، أوافق على أنه من المنطقي استعراض المناطق المختلفة واحدة تلو الأخرى مع المرشد لتحديد المشكلات وتحسين وثائق Doxygen.
أرى هذا مشروعًا قياسيًا لكنني متأكد من أن هناك تحسينات أخرى متعلقة بوثائق واجهة برمجة التطبيقات التي يمكن إجراؤها بعد انتهاء مشروع GSoD. على سبيل المثال، التوصل إلى دليل نمط التوثيق وإضافته إلى موقع wiki، حتى يعرف المساهمون كيفية توثيق التعليمة البرمجية التي يضيفونها.
يسعدني أن أساعدك في مهام مثل هذه بعد انتهاء GSoD. أنا متأكد من أن ScummVM يمكن أن يستعين بكاتب تقني سيتأكد من أن مستند واجهة برمجة التطبيقات الخاص به ذو جودة جيدة وقابلية الاستخدام. أرى أيضًا أنّ هناك مشاريع مستندات أخرى في المستقبل يمكنني مساعدتك فيها، مثل إنشاء دليل حول كيفية العمل باستخدام المكوّنات الإضافية.