इस पेज पर Google Docs के सीज़न के लिए स्वीकार किए गए एक तकनीकी लेखन प्रोजेक्ट की जानकारी है.
प्रोजेक्ट की खास जानकारी
- ओपन सोर्स संगठन:
- ScummVM
- तकनीकी लेखक:
- b-gent
- प्रोजेक्ट का नाम:
- Doxygen की मदद से, सोर्स कोड के दस्तावेज़ को बेहतर बनाएं
- प्रोजेक्ट की अवधि:
- मानक अवधि (तीन महीने)
प्रोजेक्ट का विवरण
मौजूदा ScummVM API (सोर्स कोड) दस्तावेज़ यहां पब्लिश किया गया है: https://doxygen.scummvm.org/modules.html
अफ़सोस की बात यह है कि इसमें कई क्षेत्रों में कमी है:
1) व्यावहारिक रूप से इसका कोई स्ट्रक्चर नहीं है, सभी जानकारी एक ही लेवल पर फ़्लोट कर रही है.
2) C++ एलिमेंट को उनमें से कुछ एलिमेंट के साथ अलग-अलग तरीके से दर्ज किया गया है और इनके बारे में भी जानकारी नहीं दी गई है. संगठन ने इसे मुख्य समस्याओं में से एक बताया है.
3) आउटपुट में पुराना और काम न करने वाला कॉन्टेंट अब भी दिख रहा है.
4) डॉक्सीजन टैगिंग की भाषा और उपयोग को अधिक संगत बनाया जाना चाहिए. इसके लिए नियमों का एक सेट ज़रूरी है. आने वाले समय में इस प्रोजेक्ट के स्टाइल गाइड के तौर पर, यह नियम बनाया जा सकता है.
5) इस पेज पर इस्तेमाल किए गए doxygen सीएसएस में सुधार किया जा सकता है, ताकि यह ScummVM वेबसाइट से मिलता-जुलता हो: https://www.scummvm.org
Docs के सीज़न के दौरान ये सभी समस्याएं हल की जा सकती हैं.
Docs ऐप्लिकेशन के इस सीज़न के साथ एक ड्राफ़्ट PR शामिल होता है, जिसे मैंने प्रोजेक्ट में खोला था. यह मेरे सुझाव में किए गए कुछ संभावित सुधारों को दिखाता है: https://github.com/scummvm/scummvm/pull/2361 इसमें क्या है, इसके बारे में कुछ जानकारी और फ़र्क़ देखने के लिए, यहां दी गई जानकारी देखें.
PR में करीब-करीब यही होता है:
1) मुझे लगता है कि संभावित नए योगदान देने वालों के लिए अभी सबसे ज़्यादा भ्रमित करने वाली चीज़ है, और आम तौर पर वर्तमान API दस्तावेज़ को देखने वाले हर व्यक्ति की संरचना की कमी है. पेश है स्ट्रक्चर्ड एपीआई दस्तावेज़ से दस्तावेज़ आसानी से पढ़ा जा सकेगा, उसे आसानी से खोजा जा सकेगा, और उसका इस्तेमाल आसानी से किया जा सकेगा. इसलिए मेरा PR 'सामान्य' फ़ोल्डर में सभी हेडर फ़ाइलों में डॉक्सीजन समूह पेश करता है. इस नए स्ट्रक्चर की मदद से, अगर कोई व्यक्ति ओएस से जुड़े एपीआई के लिए दस्तावेज़ (उदाहरण के लिए) खोजना चाहता है, तो वह उसे नेविगेशन में आसानी से ढूंढ सकता है.
2) इस दस्तावेज़ को बनाने के लिए एक नई Doxygen कॉन्फ़िगरेशन फ़ाइल सेट अप की गई है.
3) एक 'links.doxyfile' फ़ाइल, जिससे पूरे दस्तावेज़ में इस्तेमाल किए जाने वाले सभी लिंक सिंगल सोर्स किए जा सकते हैं. डॉक्सीजन के साथ काम करते समय यह एक उपयोगी तरीका है.
4) एक संशोधित doxygen CSS. यह फ़िलहाल किसी दूसरे ओपन-सोर्स प्रोजेक्ट से लिया गया है और यह सिर्फ़ एक शुरुआती पॉइंट है. आम तौर पर, डॉक्सीजन पेज का लुक और स्टाइल, ScummVM वेब पेज से मिलता-जुलता होना चाहिए.
इसमें पीआर में क्या शामिल नहीं है, लेकिन जिस पर काम करने की ज़रूरत है वह कॉन्टेंट है. इससे मेरा मतलब है कि कोड के उन ज़रूरी हिस्सों की पहचान करें जिन्हें दस्तावेज़ में नहीं रखा गया है, जिन्हें दस्तावेज़ से हटा दिया जाना चाहिए. ऐसा भी हो सकता है कि जिन हिस्सों को पूरा दस्तावेज़ के तौर पर दर्ज नहीं किया गया है वे पुराने हो चुके हों. मैंने इस प्रोजेक्ट पर पहले काम नहीं किया है. इसलिए, इसे हासिल करने के लिए किसी मेंटॉर के मार्गदर्शन की ज़रूरत होगी.
निश्चित तौर पर, चाहे हम पीआर से किसी भी चीज़ को लागू करें, वह संगठन के साथ चर्चा करने पर निर्भर करता है. मेरा आइडिया था कि काम शब्दों से ज़्यादा तेज़ होते हैं. इसलिए, मैंने ऐप्लिकेशन में सिर्फ़ यह जानकारी देने की जगह यह दिखाने का फ़ैसला किया कि मैं क्या कर सकता/सकती हूं.
संगठन ने इस प्रोजेक्ट के लिए, अनुमानित टाइमलाइन दी है हफ़्ता मुख्य टास्क दूसरा हफ़्ता (9/14 से पहले) प्रस्ताव पर चर्चा और समीक्षाएं पहला हफ़्ता (9/21) दस्तावेज़ सबमिट करना दूसरा हफ़्ता (9/21) दिन भर के लिए (9/21) सामान्य कोड - ओएस, एफ़एस/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता स्ट्रक्चर सबमिट करना) जारी रखने वाला कोड - ओएस, छह/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता/हफ़्ता स्ट्रक्चर सबमिट करना.
मैं बस एक बदलाव का सुझाव देता हूं. उसकी शुरुआत स्ट्रक्चर पर काम करने से होगी, जैसा कि पहले ही बताया जा चुका है. यह काम पहले और दूसरे हफ़्ते में, डॉक्सीजन बिल्ड सेटअप (जिसे काफ़ी हद तक पहले ही पूरा हो चुका है) और Doxygen स्किन को रीफ़्रेश करके किया जा सकता है. इसके बाद, मैं इस बात से सहमत हूँ कि समस्या की पहचान करने और डॉक्सीजन के दस्तावेज़ को बेहतर बनाने के लिए, मेंटॉर के साथ एक-एक करके अलग-अलग विषयों पर जाना सबसे सही रहेगा.
मुझे यह स्टैंडर्ड-अवधि वाला प्रोजेक्ट दिख रहा है, लेकिन मुझे यकीन है कि एपीआई दस्तावेज़ से जुड़े दूसरे सुधार भी हैं, जो GSoD प्रोजेक्ट के पूरा होने के बाद किए जा सकते हैं. उदाहरण के लिए, दस्तावेज़ स्टाइल गाइड तैयार करना और उसे विकी में जोड़ना, ताकि योगदान देने वालों को पता चल सके कि उन्हें जोड़े जा रहे कोड को किस तरह दर्ज करना चाहिए.
GSoD के खत्म होने के बाद, हम इस तरह के कामों में आपकी मदद करेंगे. मुझे यकीन है कि ScummVM किसी तकनीकी राइटर का इस्तेमाल कर सकता है और यह पक्का करेगा कि उसका एपीआई दस्तावेज़ अच्छी क्वालिटी का हो और इस्तेमाल के हिसाब से सही हो. मैं यह भी देख सकती हूं कि आने वाले समय में दूसरे दस्तावेज़ प्रोजेक्ट हैं, जिनमें मैं आपकी मदद कर सकता हूं. जैसे कि प्लगिन के साथ काम करने के तरीके के बारे में गाइड बनाना.