इस पेज पर, तकनीकी लेखन वाले उस प्रोजेक्ट की जानकारी दी गई है जिसे Google Season of Docs के लिए स्वीकार किया गया है.
प्रोजेक्ट की खास जानकारी
- ओपन सोर्स संगठन:
- ScummVM
- टेक्निकल राइटर:
- b-कमज़ोर
- प्रोजेक्ट का नाम:
- Doxygen की मदद से, सोर्स कोड के दस्तावेज़ को बेहतर बनाना
- प्रोजेक्ट की अवधि:
- स्टैंडर्ड अवधि (तीन महीने)
प्रोजेक्ट का विवरण
ScommVM API (सोर्स कोड) का मौजूदा दस्तावेज़ यहां पब्लिश किया गया है: https://doxygen.scurmvm.org/modules.html
हालांकि, यह सुविधा कई जगहों पर उपलब्ध नहीं है:
1) इसका व्यावहारिक रूप से कोई स्ट्रक्चर नहीं है, सभी जानकारी एक ही लेवल पर फ़्लोटिंग होती है.
2) C++ एलिमेंट को अलग-अलग तरीके से दस्तावेज़ में शामिल किया गया है. इनमें से कुछ एलिमेंट को दस्तावेज़ में शामिल ही नहीं किया गया है. संगठन ने इसे मुख्य समस्याओं में से एक बताया है.
3) आउटपुट में अब भी पुराना और काम न करने वाला कॉन्टेंट दिख रहा है.
4) doxygen टैगिंग की भाषा और इस्तेमाल को ज़्यादा एक जैसा बनाया जाना चाहिए. इसके लिए नियमों का एक सेट ज़रूरी है, जो इस प्रोजेक्ट के लिए भविष्य के दस्तावेज़ की स्टाइलगाइड का आधार हो सकता है.
5) इस पेज पर इस्तेमाल की गई doxygen सीएसएस को बेहतर बनाया जा सकता है, ताकि इसे ScummVM की वेबसाइट: https://www.scummvm.org से ज़्यादा मिलता-जुलता बनाया जा सके
Docs प्रोजेक्ट के सीज़न के दौरान, ये सभी समस्याएं हल की जा सकती हैं.
Docs ऐप्लिकेशन के इस सीज़न में एक ड्राफ़्ट पीआर भी मौजूद है. इस पीआर को मैंने प्रोजेक्ट में खोला है, ताकि मेरे सुझाए गए कुछ संभावित सुधारों को दिखाया जा सके: https://github.com/scumvm/sूरmvm/pull/2361 इसमें क्या है और अंतर देखने के लिए ब्यौरा देखें.
पीआर में ये काम शामिल होते हैं:
1) मुझे लगता है कि मौजूदा एपीआई दस्तावेज़ में स्ट्रक्चर की कमी है. इस वजह से, संभावित नए योगदानकर्ताओं और आम तौर पर इसे देखने वाले सभी लोगों को भ्रम हो रहा है. स्ट्रक्चर्ड एपीआई डॉक्यूमेंटेशन की शुरुआत करने से, दस्तावेज़ को पढ़ना और समझना आसान हो जाएगा. साथ ही, इससे दस्तावेज़ को इस्तेमाल करने में आसानी होगी. यही वजह है कि मेरा पीआर 'सामान्य' फ़ोल्डर में सभी हेडर फ़ाइलों के लिए डॉक्सीजन ग्रुप पेश करता है. इस नए स्ट्रक्चर की मदद से, अगर किसी को ओएस से जुड़े एपीआई के दस्तावेज़ खोजने हैं, तो वे नेविगेशन में जाकर उन्हें आसानी से ढूंढ सकते हैं.
2) इस दस्तावेज़ को बनाने के लिए, एक नई doxygen कॉन्फ़िगरेशन फ़ाइल सेट अप की गई है.
3) 'links.doxyfile' फ़ाइल, जिसमें पूरे दस्तावेज़ सेट में इस्तेमाल किए गए सभी लिंक एक ही सोर्स से लिए जा सकते हैं. doxygen के साथ काम करते समय, यह एक काम का तरीका है.
4) बदली गई doxygen सीएसएस. फ़िलहाल, इसे किसी दूसरे ओपन सोर्स प्रोजेक्ट से लिया गया है और यह सिर्फ़ शुरुआत है. आम तौर पर, doxygen पेज का लुक-एंड-फ़ील, ScummVM वेब पेज से काफ़ी हद तक मेल खाना चाहिए.
प्रेस रिलीज़ में कॉन्टेंट के बारे में नहीं बताया जाता, लेकिन इस पर काम करना ज़रूरी है. इसका मतलब है कि कोड के उन ज़रूरी हिस्सों की पहचान करना जिन्हें दस्तावेज़ में शामिल नहीं किया गया है, ऐसे हिस्सों की पहचान की जा सकती है जिनका ज़रूरी दस्तावेज़ नहीं है या कोड के पुराने हिस्सों को दस्तावेज़ से हटाया जाना चाहिए. मैंने पहले कभी इस प्रोजेक्ट पर काम नहीं किया है. इसलिए, इसे पूरा करने के लिए मुझे किसी मेंटर की मदद चाहिए.
हालांकि, हम पीआर में बताई गई किसी भी बात को लागू करेंगे या नहीं, यह संगठन के साथ बातचीत के बाद तय होगा. मेरा मानना है कि शब्दों की तुलना में काम ज़्यादा असरदार होते हैं. इसलिए, मैंने ऐप्लिकेशन में सिर्फ़ बताने के बजाय, यह दिखाने का फ़ैसला लिया कि मैं क्या कर सकता हूं.
संगठन ने इस प्रोजेक्ट के लिए, यह अनुमानित टाइमलाइन दी है: हफ़्ता मुख्य टास्क हफ़्ता 0 (14/9 से पहले) प्रस्ताव पर चर्चा और समीक्षाएं हफ़्ता 1 (14/9) Doxygen बिल्ड सेट अप करना हफ़्ता 2 (21/9) Doxygen की स्किन रीफ़्रेश करना (कम प्राथमिकता) हफ़्ता 3 (28/9) सामान्य कोड - OSystem, FS, डेटा स्ट्रक्चर, स्ट्रिंग वगैरह हफ़्ता 4 (05/10) सामान्य कोड - जारी है हफ़्ता 5 (12/10) इंजन - सामान्य कोड और सैंपल इंजन हफ़्ता 6 (19/10) ग्राफिक्स हफ़्ता 7 (26/10) ऑडियो हफ़्ता 8 (02/11) वीडियो, इमेज हफ़्ता 9 (09/11) बैकएंड - प्लैटफ़ॉर्म, ग्राफ़िक्स, इवेंट हफ़्ता 10 (23/11) बैकएंड - जारी है हफ़्ता 11 (30/11) प्रोजेक्ट की खास जानकारी और सबमिशन
जैसा कि पहले ही बताया जा चुका है कि मैं सिर्फ़ स्ट्रक्चर पर काम करके शुरुआत करने का सुझाव दूंगा/दूंगी. यह काम पहले और दूसरे हफ़्ते में किया जा सकता है. साथ ही, doxygen बिल्ड सेटअप (जो ज़्यादातर पहले से ही किया जा चुका है) और Doxygen की स्किन रीफ़्रेश की जा सकती है. इसके बाद, मैं इस बात से सहमत हूं कि समस्याओं की पहचान करने और doxygen दस्तावेज़ को बेहतर बनाने के लिए, मेंटर के साथ अलग-अलग हिस्सों को एक-एक करके देखना सबसे सही है.
मुझे लगता है कि यह एक स्टैंडर्ड प्रोजेक्ट है. हालांकि, मुझे यकीन है कि एपीआई दस्तावेज़ से जुड़े अन्य सुधार, जीएसओडी प्रोजेक्ट खत्म होने के बाद किए जा सकते हैं. उदाहरण के लिए, दस्तावेज़ के लिए स्टाइल गाइड बनाना और उसे विकी में जोड़ना, ताकि योगदान देने वाले लोगों को पता हो कि उन्हें जो कोड जोड़ना है उसका दस्तावेज़ कैसे बनाना चाहिए.
जीएसओडी खत्म होने के बाद, इस तरह के कामों में हमें आपकी मदद करके खुशी होगी. मुझे यकीन है कि ScummVM के लिए किसी तकनीकी लेखक की ज़रूरत है, जो यह पक्का कर सके कि उसका एपीआई दस्तावेज़ अच्छी क्वालिटी का हो और उसे इस्तेमाल किया जा सके. मुझे यह भी पता है कि आने वाले समय में, Docs से जुड़े ऐसे और भी प्रोजेक्ट होंगे जिनमें हम आपकी मदद कर सकते हैं. जैसे, प्लग इन के साथ काम करने का तरीका बताने वाली गाइड बनाना.