مشروع ScummVM

تحتوي هذه الصفحة على تفاصيل مشروع كتابة فنية تم قبوله في "موسم مستندات Google".

ملخص المشروع

مؤسسة مفتوحة المصدر:
ScummVM
الكاتب الفني:
b-gent
اسم المشروع:
تحسين مستندات رمز المصدر من خلال Doxygen
مدة المشروع:
المدة العادية (3 أشهر)

وصف المشروع

يمكنك الاطّلاع على مستندات ScummVM API (الرمز المصدر) الحالية هنا: https://doxygen.scummvm.org/modules.html

للأسف، تنقصه في العديد من الجوانب:

1) لا تتضمّن هذه الصفحة بنية، بل تظهر كل المعلومات على المستوى نفسه.

2) يتم توثيق عناصر C++ بشكل غير متّسق، مع عدم توثيق بعض منها على الإطلاق. هذا شيء تذكره المؤسسة باعتباره أحد المشكلات الرئيسية.

3) لا يزال يتم عرض المحتوى القديم والمنتهي الصلاحية في الإخراج.

4) يجب أن تكون لغة وضع علامات doxygen واستخدامها أكثر اتساقًا. يجب وضع مجموعة من القواعد لهذا الغرض، ما يمكن أن يكون أساسًا لدليل أسلوب مستندات مستقبلي لهذا المشروع.

5) يمكن تحسين CSS بلغة Doxygen المستخدمة في هذه الصفحة لجعلها أكثر تشابهًا مع موقع ScummVM الإلكتروني: https://www.scummvm.org

يمكن معالجة كل هذه المشاكل خلال مشروع "موسم المستندات".

يرافق طلب المشاركة في "موسم المستندات" هذا مسودة طلب إعادة نظر فتحتها في المشروع لعرض بعض التحسينات المحتملة التي أقترحها: https://github.com/scummvm/scummvm/pull/2361 يمكنك الاطّلاع على الوصف الوارد هناك لمعرفة بعض التفاصيل حول ما يحتويه والاطّلاع على الفرق.

في ما يلي مهام العلاقات العامة تقريبًا:

1) أعتقد أنّ عدم التسلسل هو أكثر ما يربك المساهمين المحتملين الجدد، وجميع المستخدمين الذين يطّلعون على مستند واجهة برمجة التطبيقات الحالي. سيؤدي تقديم مستندات منظَّمة لواجهات برمجة التطبيقات إلى تحسين سهولة القراءة والعثور على مجموعة المستندات، وبالتالي سهولة استخدامها. لهذا السبب، تقدّم طلب المراجعة الخاص بي مجموعات doxygen لجميع ملفات الرأس في المجلد "common". باستخدام هذه البنية الجديدة، إذا أراد أحد المستخدمين العثور على مستندات لواجهة برمجة التطبيقات ذات الصلة بنظام التشغيل (على سبيل المثال)، يمكنه العثور عليها بسهولة في شريط التنقّل.

2) يتم إعداد ملف إعداد Doxygen جديد لإتاحة إنشاء هذه المستندات.

3) ملف "links.doxyfile" يمكن أن تكون جميع الروابط المستخدمة من خلاله في مجموعة مستندات مصدر واحد. آلية مفيدة عند التعامل مع الدوكسجين.

4) ملف CSS معدَّل من doxygen يتم حاليًا الحصول على هذه البيانات من مشروع آخر مفتوح المصدر، وهي ليست سوى نقطة بداية. من المفترض أن يكون مظهر صفحة doxygen وأسلوبها متسقَين إلى حدٍ ما مع صفحة الويب الخاصة بتطبيق ScummVM.

إنّ المحتوى نفسه هو ما لا يشمله قسم العلاقات العامة، ولكن يجب العمل عليه بالتأكيد. أقصد بذلك تحديد الأجزاء الأساسية من الرمز البرمجي التي لم يتم توثيقها أو التي لم يتم توثيقها بشكل كافٍ أو الأجزاء القديمة من الرمز البرمجي التي يجب إزالتها من المستندات. بما أنّني لم أعمل في المشروع من قبل، سنحتاج إلى إرشادات من أحد الخبراء لتحقيق ذلك.

بالطبع، يعتمد تنفيذ أيّ من اقتراحات العلاقات العامة على مناقشة مع المؤسسة. كانت فكرتي أن الإجراءات تتحدث بصوت أعلى من الكلمات، لذلك قررت أن أوضح ما يمكنني فعله بدلاً من وصفها في التطبيق.

قدّمت المؤسسة المخطط الزمني التقريبي التالي لهذا المشروع: الأسبوع المهمة الرئيسية الأسبوع 0 (قبل 14 أيلول (سبتمبر)) المناقشة بشأن الاقتراح ومراجعته الأسبوع 1 (14 أيلول (سبتمبر)) إعداد عملية إنشاء Doxygen الأسبوع 2 (21 أيلول (سبتمبر)) تحديث مظهر Doxygen (أولوية منخفضة) الأسبوع 3 (28 أيلول (سبتمبر)) الرمز البرمجي الشائع - OSystem وFS وData Structures وStrings وما إلى ذلك الأسبوع 4 (5 تشرين الأول (أكتوبر)) الرمز البرمجي الشائع - متابعة الأسبوع 5 (12 تشرين الأول (أكتوبر)) المحرّكات - الرمز البرمجي الشائع ونماذج المحرّكات الأسبوع 6 (19 تشرين الأول (أكتوبر)) رسومات فنية الأسبوع 7 (26 تشرين الأول (أكتوبر)) صوت الأسبوع 8 (2 تشرين الثاني (نوفمبر)) الفيديوهات والصور الأسبوع 9 (9 تشرين الثاني (نوفمبر)) الخلفيات - المنصات والرسومات والأحداث الأسبوع 10 (23 تشرين الثاني (نوفمبر)) الخلفيات - متابعة الأسبوع 11 (30 تشرين الثاني (نوفمبر)) ملخّص المشروع وإرساله

التغيير الوحيد الذي أقترحه هو البدء بالعمل على البنية، كما سبق ذكره. يمكن إجراء ذلك في الأسبوعَين الأول والثاني، إلى جانب إعداد عملية إنشاء Doxygen (التي تم إجراؤها إلى حد كبير) وإعادة تحميل واجهة Doxygen. بعد ذلك، أوافق على أنّه من المنطقي الاطّلاع على الجوانب المختلفة واحدًا تلو الآخر مع المرشد لتحديد المشاكل وتحسين مستندات doxygen.

أرى أنّ هذا المشروع عادي الطول، ولكنّني متأكّد من أنّ هناك تحسينات أخرى متعلّقة بوثائق واجهة برمجة التطبيقات يمكن إجراؤها بعد انتهاء مشروع GSoD. على سبيل المثال، إنشاء دليل أسلوب للمستندات وإضافته إلى الموسوعة الإلكترونية، حتى يتعرّف المساهمون على كيفية توثيق الرموز البرمجية التي يضيفونها.

سيكون من دواعي سروري مساعدتك في مهام مثل هذه بعد انتهاء GSoD. أنا متأكّد من أنّ ScummVM بحاجة إلى كاتب فني يحرص على أن يكون مستند واجهة برمجة التطبيقات الخاص به عالي الجودة وسهل الاستخدام. أرى أيضًا أنّ هناك مشاريع مستندات أخرى مستقبلية يمكنني مساعدتك في تنفيذها، مثل إنشاء دليل حول كيفية استخدام الإضافات.