این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد 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
تمام این مشکلات در طول پروژه Season of Docs قابل حل است.
این برنامه Season of Docs با پیش نویس روابط عمومی همراه است که من در پروژه باز کردم تا برخی از پیشرفت های بالقوه ای را که پیشنهاد می کنم نشان دهم: https://github.com/scummvm/scummvm/pull/2361 توضیحات را در آنجا ببینید برای جزئیات بیشتر شامل و برای مشاهده تفاوت است.
این تقریباً چیزی است که روابط عمومی شامل:
1) فکر می‌کنم آنچه در حال حاضر برای مشارکت‌کنندگان بالقوه جدید و عموماً همه کسانی که سند API فعلی را مشاهده می‌کنند، گیج‌کننده‌ترین فقدان ساختار است. معرفی اسناد API ساختار یافته خوانایی، یافتن و در نتیجه قابلیت استفاده از docset را بهبود می بخشد. به همین دلیل است که روابط عمومی من گروه های doxygen را به تمام فایل های هدر در پوشه مشترک معرفی می کند. با این ساختار جدید، اگر کسی بخواهد برای API مربوط به سیستم عامل (به عنوان مثال) اسنادی را پیدا کند، به راحتی می تواند آن را در مسیریابی پیدا کند.
2) یک فایل پیکربندی doxygen جدید برای فعال کردن ساخت این مستندات تنظیم شده است.
3) یک فایل 'links.doxyfile' که از آن می توان همه پیوندهای استفاده شده در سراسر docset را تک منبع تهیه کرد. یک مکانیسم مفید هنگام کار با داکسیژن.
4) CSS doxygen اصلاح شده. این در حال حاضر از پروژه منبع باز دیگری گرفته شده است و تنها یک نقطه شروع است. در حالت ایده آل، ظاهر و ظاهر صفحه doxygen باید کمابیش با صفحه وب ScummVM سازگار باشد.
چیزی که روابط عمومی پوشش نمی دهد اما قطعا باید روی آن کار شود، خود محتوا است. منظور من از این کار، شناسایی بخش‌های اساسی کد است که مستند نیستند، آن‌هایی که به اندازه کافی مستند نیستند، یا بخش‌های قدیمی کد که باید از اسناد حذف شوند. از آنجایی که قبلاً در پروژه کار نکرده ام، برای رسیدن به این هدف به راهنمایی یک مربی نیاز است.
البته این که آیا چیزی از روابط عمومی را اجرا کنیم یا خیر، به بحث با سازمان بستگی دارد. ایده من این بود که عملکردها بلندتر از کلمات صحبت می کنند، بنابراین تصمیم گرفتم به جای اینکه فقط آن را در برنامه توصیف کنم، نشان دهم که چه کاری می توانم انجام دهم.
سازمان جدول زمانی تقریبی زیر را برای این پروژه ارائه کرده است: هفته وظیفه اصلی هفته 0 (قبل از 14/9) بحث و بررسی پیشنهادات هفته 1 (9/14) راه اندازی Doxygen هفته 2 (9/21) تازه کردن پوست Doxygen ( اولویت پایین) هفته 3 (9/28) کد مشترک - سیستم عامل، FS، ساختارهای داده، رشته ها، و غیره. هفته 4 (10/05) کد مشترک - ادامه هفته 5 (10/12) موتورها - کد مشترک و موتور نمونه هفته 6 (10/19) گرافیک هفته 7 (10/26) صوتی هفته 8 (11/02) ویدیو، تصاویر هفته 9 (11/09) Backends - پلتفرم ها، گرافیک، رویدادهای هفته 10 (11/23) Backends هفته 10 (11/23) - هفته ادامه 11 (11/30) خلاصه و ارسال پروژه
تنها تغییری که من پیشنهاد می‌کنم این است که همانطور که قبلاً ذکر شد با کار بر روی ساختار شروع کنید. این کار را می‌توان در هفته‌های 1 و 2، همراه با تنظیم ساخت داکسیژن (که تا حد زیادی در حال حاضر انجام شده است) و نوسازی پوست Doxygen انجام داد. پس از آن، من موافقم که منطقی‌تر است که برای شناسایی مشکلات و بهبود مستندات داکسیژن، بخش‌های مختلف را یکی یکی با مربی مرور کنیم.
من این را یک پروژه با طول استاندارد می‌دانم، اما مطمئن هستم که پیشرفت‌های دیگری در رابطه با اسناد API وجود دارد که می‌توان پس از پایان پروژه GSoD انجام داد. به عنوان مثال، ایجاد یک راهنمای سبک مستندسازی و افزودن آن به ویکی، به طوری که مشارکت کنندگان بدانند چگونه باید کدی را که اضافه می کنند، مستند کنند.
من با کمال میل در کارهایی مانند این پس از پایان GSoD کمک خواهم کرد. من مطمئن هستم که ScummVM می تواند از یک نویسنده فنی استفاده کند که مطمئن شود سند API آن از کیفیت و قابلیت استفاده خوبی برخوردار است. همچنین می‌توانم ببینم که پروژه‌های مستند آینده دیگری نیز وجود دارد که می‌توانم به شما کمک کنم، مانند ایجاد راهنمای نحوه کار با افزونه‌ها.