आंतरिक लाइब्रेरी के लिए डॉक्स ऑक्सीजन कमेंट ब्लॉक कहाँ रखें - एच में या सीपीपी फाइलों में? [बन्द है]

Question

सामान्य ज्ञान बताता है कि Doxygen कमेंट ब्लॉक को उन हेडर फ़ाइलों में रखना पड़ता है जहाँ कक्षाएं, संरचना, एनम, फ़ंक्शन, घोषणाएँ हैं। मैं मानता हूं कि यह पुस्तकालयों के लिए एक ध्वनि तर्क है जिसका अर्थ है कि इसके स्रोत के बिना वितरित किया जाना चाहिए (केवल ऑब्जेक्ट कोड के साथ हेडर और लिबास)।

लेकिन ... मैं ठीक विपरीत दृष्टिकोण के बारे में सोच रहा था जब मैं कंपनी के लिए एक आंतरिक (या खुद के लिए एक साइड प्रोजेक्ट के रूप में) पुस्तकालय विकसित कर रहा हूं जिसका उपयोग इसके पूर्ण स्रोत कोड के साथ किया जाएगा। मैं प्रपोजल फाइलों (एचपीपी, आईएनएल, सीपीपी, आदि) में बड़े कमेंट ब्लॉक लगाने का प्रस्ताव रखता हूं ताकि हेडर में घोषित वर्गों और कार्यों के पूर्णांक को अव्यवस्थित न कर सके।

पेशेवरों:

• हेडर फ़ाइलों में कम अव्यवस्था, केवल कार्यों के वर्गीकरण को जोड़ा जा सकता है।
• जब टिप्पणी का उपयोग किया जाता है, जब उदाहरण के लिए Intellisense का उपयोग किया जाता है, तो यह बंद नहीं होता है - यह एक दोष है जो मैंने तब देखा है जब मेरे पास .H फ़ाइल में एक फ़ंक्शन के लिए एक टिप्पणी ब्लॉक है और उसी में इसकी इनलाइन परिभाषा है। लेकिन .INL फ़ाइल से शामिल किया गया।

विपक्ष:

• (स्पष्ट एक) टिप्पणी ब्लॉक हेडर फाइलों में नहीं हैं जहां घोषणाएं हैं।

तो, आपको क्या लगता है और संभवतः सुझाव देते हैं?

Answer 1

दस्तावेज़ीकरण रखो जहां लोग इसे पढ़ेंगे और लिखेंगे जैसा कि वे उपयोग कर रहे हैं और कोड पर काम कर रहे हैं।

कक्षा की टिप्पणियाँ कक्षाओं के सामने जाती हैं, विधियों के सामने विधि टिप्पणियाँ।

यह सुनिश्चित करने का सबसे अच्छा तरीका है कि चीजों को बनाए रखा जाए। यह आपकी हेडर फ़ाइलों को अपेक्षाकृत दुबला रखता है और लोगों के छूने के मुद्दे से बचने के तरीके को अपडेट करता है जिससे डॉक्स हेडर गंदे और ट्रिगर हो सकते हैं। मैं वास्तव में लोगों को पता है कि बाद में प्रलेखन लिखने के लिए एक बहाने के रूप में उपयोग करते हैं !

Comments

मेरे पास एक दर्दनाक अनुस्मारक है कि हेडर में डॉक्स से क्यों बचा जाना चाहिए - वर्ग की घोषणा में विधि टिप्पणियों को डालने के लिए एक वरिष्ठ वीपी द्वारा कहा गया था और खुद को वास्तव में बाद के लिए टिप्पणी संपादन को बचाने के लिए पाया क्योंकि उन हेडर को मारने से एक 45 मिनट का निर्माण होता है !

— एंडी डेंट

डाउनवोटिंग नहीं, बस सवाल करना: यदि मैं यह जानने की कोशिश कर रहा हूं कि एपीआई (यहां तक ​​कि एक आंतरिक भी) क्या करता है, तो मुझे प्रलेखन को खोजने के लिए सभी कोड के माध्यम से .cpp और उतारा नहीं करना होगा। मैं मानता हूँ कि यह एक दर्द होगा यदि आप केवल ग्राहक के दृष्टिकोण से अधिक दस्तावेज करते हैं कि विधि क्या कर रही है (जैसे यह कैसे करता है), लेकिन आप वैसे भी नहीं कर रहे हैं, है ना?

— TED

आपके दस्तावेज़ को जनरेट करने के लिए Doxygen का उपयोग करने का पूरा बिंदु जनरेट किए गए दस्तावेज़ को सुलभ बनाना है। हमारे पास एक आंतरिक वेब सर्वर है जहां Doxygen आउटपुट जाता है और हम चर्चा में उस सर्वर के पृष्ठों के लिंक का उपयोग कर सकते हैं। यह भी व्यापक डिजाइन मुद्दों पर चर्चा करने वाले अतिरिक्त पृष्ठों के साथ वर्ग या विधि प्रलेखन को जोड़ता है।

— एंडी डेंट

कार्यान्वयन चर्चा कितनी सार्वजनिक होनी चाहिए, यह तय करना एक दिलचस्प मुद्दा है। निश्चित रूप से अगर कोई विशेष एल्गोरिथ्म या साइड-इफेक्ट्स हैं, तो मैं उनके बारे में लाइब्रेरी के एक ग्राहक के रूप में जानना पसंद करूंगा। कभी-कभी केवल अनुचर को ही पता होना चाहिए और Doxygen के पास सशर्त वर्गों को चिह्नित करने का एक आसान तरीका है, इसलिए आप विभिन्न दृष्टिकोणों के लिए अलग-अलग डॉक्स उत्पन्न कर सकते हैं।

— एंडी डेंट

Answer 2

मैं इस तथ्य का उपयोग करना पसंद करता हूं कि नामों को कई स्थानों पर प्रलेखित किया जा सकता है।

हेडर फ़ाइल में, मैं विधि का एक संक्षिप्त विवरण लिखता हूं, और इसके सभी मापदंडों का दस्तावेजीकरण करता हूं - ये स्वयं विधि के कार्यान्वयन की तुलना में बदलने की संभावना कम हैं, और यदि वे करते हैं, तो फ़ंक्शन प्रोटोटाइप को किसी भी मामले में बदलना होगा। ।

मैं वास्तविक कार्यान्वयन के बगल में स्रोत फ़ाइलों में लंबे समय तक प्रारूपण दस्तावेज़ रखता हूं, इसलिए विधि विकसित होने पर विवरण को बदला जा सकता है।

उदाहरण के लिए:

mymodule.h

/// @brief This method adds two integers.
/// @param a First integer to add.
/// @param b Second integer to add.
/// @return The sum of both parameters.
int add(int a, int b);

mymodule.cpp

/// This method uses a little-known variant of integer addition known as
/// Sophocles' Scissors. It optimises the function's performance on many
/// platforms that we may or may not choose to target in the future.
/// @TODO make sure I implemented the algorithm correctly with some unit tests.
int add(int a, int b) {
  return b + a;
}

Comments

मुझे यह तरीका पसंद है, लेकिन यह AUTOBRIEF के साथ असंगत लगता है। मुझे यह जानने में दिलचस्पी होगी कि क्या उत्पादित कई ब्रीफ्स को खत्म करने के लिए कॉन्फ़िगरेशन वर्कअराउंड है।

— आरोन राइट

मुझे यह तरीका भी पसंद है, यह कार्यान्वयन में एक अच्छा संतुलन प्रदान करता है।

— Xofo

मैं अपनी मशीन पर इस विधि को पुन: पेश करने में सक्षम नहीं हूं, Doxygen 1.8.15 का उपयोग कर रहा हूं। पैरामीटर प्रलेखन प्रकट नहीं होता है, केवल संक्षिप्त और विस्तृत विवरण।

— दंडिया

परिशिष्ट: समारोह के ब्लॉक के अंदर विस्तृत विवरण की नियुक्ति को बदलना मेरे लिए यह काम करता है। विवरण अब हेडर डॉक्स में विवरणों के अंत में संलग्न है।

— दंडिया

Answer 3

हेडर में टिप्पणियां होने का मतलब है कि यदि कोई टिप्पणी बदली जाती है तो एक वर्ग के सभी उपयोगकर्ताओं को फिर से तैयार किया जाना चाहिए। बड़ी परियोजनाओं के लिए, कोडर्स को हेडर में टिप्पणियों को अद्यतन करने के लिए कम झुकाव होगा यदि वे अगले 20 मिनट के पुनर्निर्माण में सब कुछ खर्च करने का जोखिम उठाते हैं।

और .. चूंकि आप html डॉक को पढ़ना चाहते हैं और प्रलेखन के लिए कोड के माध्यम से ब्राउज़ नहीं करते हैं, इसलिए यह एक बड़ी समस्या नहीं है कि स्रोत फ़ाइलों में टिप्पणी ब्लॉक का पता लगाना अधिक कठिन है।

Comments

सही है, लेकिन यह एक बड़ी समस्या है अगर यह एक गतिशील पुस्तकालय को एक

— कलाकृत

Answer 4

शीर्षलेख: फाइलों को देखते समय कम "शोर" के बाद से टिप्पणियों को पढ़ना आसान है।

स्रोत: तब आपके पास टिप्पणियों को देखते हुए पढ़ने के लिए वास्तविक कार्य उपलब्ध हैं।

हम हेडर में टिप्पणी की गई सभी वैश्विक फ़ंक्शन और स्रोत में टिप्पणी की गई स्थानीय फ़ंक्शन का उपयोग करते हैं। यदि आप चाहते हैं कि आप कई बार दस्तावेज को कई बार लिखने के लिए बिना कॉपी किए कमांड कॉपीकोड कमांड को भी सम्मिलित कर सकते हैं (रखरखाव के लिए बेहतर)

हालाँकि आप परिणाम को एक साधारण कमांड के साथ अलग-अलग फ़ाइल प्रलेखन पर कॉपी कर सकते हैं। जैसे: -

मेरी file1.h

/**
 * \brief Short about function
 *
 * More about function
 */
WORD my_fync1(BYTE*);

MY file1.c

/** \copydoc my_func1 */
WORD my_fync1(BYTE* data){/*code*/}

अब आपको दोनों कार्यों पर एक ही दस्तावेज मिलता है।

यह आपको कोड फ़ाइलों में कम शोर देता है एक ही समय में आपको अंतिम आउटपुट में कई स्थानों पर प्रस्तुत किए गए दस्तावेज़ को एक जगह लिखा जाता है।

Comments

ब्लॉक की प्रतिलिपि कब बनाई जाती है?

— मेर्ट कैन एर्गुएन

Answer 5

आमतौर पर मैं इंटरफ़ेस (\ param, \ return) के लिए .h फ़ाइल और कार्यान्वयन के लिए प्रलेखन (\ विवरण) .c / .cpp / .m फ़ाइल में डाल देता हूं। Doxygen फंक्शन / मेथड डॉक्यूमेंटेशन में सब कुछ ग्रुप करता है।

Answer 6

मैंने हेडर फ़ाइल में सब कुछ डाल दिया।

मैं सब कुछ दस्तावेज़ करता हूं, लेकिन आम तौर पर केवल सार्वजनिक इंटरफ़ेस निकालता हूं।

Answer 7

मैं प्रोग्रामिंग के लिए QtCreator का उपयोग कर रहा हूं। हेडर फ़ाइल में घोषणा प्राप्त करने के लिए एक फ़ंक्शन या विधि पर एक बहुत उपयोगी ट्रिक Ctrl-Clicking में होती है।

जब हेडर फ़ाइल में विधि की टिप्पणी की जाती है, तो आप उस जानकारी को जल्दी से पा सकते हैं जिसे आप खोज रहे हैं। तो मेरे लिए, टिप्पणियाँ हेडर फ़ाइल में स्थित होनी चाहिए!

Answer 8

सी ++ में कभी-कभी कार्यान्वयन हेडर और .cpp मॉड्यूल के बीच विभाजित किया जा सकता है। यहाँ पर ऐसा लगता है कि इसे हेडर फाइल में डाल दिया गया है क्योंकि यह एकमात्र ऐसा स्थान है जहाँ सभी सार्वजनिक कार्यों और तरीकों की गारंटी है।