मैं Doxygen का उपयोग कर "टिप्पणी" खंड में एकाधिक पैराग्राफ कैसे शामिल करूं?

Question

मैं अंत में कोण कोष्ठक कर माइक्रोसॉफ्ट के एक्सएमएल प्रलेखन प्रारूप द्वारा मुझ पर लगाए गए दे रहा हूँ (और बिंदु क्या है, MSVC पर्यावरण के बाद से अभी भी कुछ भी फैंसी इसके साथ सी ++ के लिए परियोजनाओं नहीं है) और स्विचिंग मेरी एक जैवडोक शैली वाक्यविन्यास के साथ Doxygen का उपयोग करने के लिए वर्तमान परियोजना।

यह शानदार है। इनलाइन दस्तावेज पढ़ने और टाइप करने के लिए बहुत आसान है, और जेनरेट आउटपुट इतना अधिक उपयोगी और बहुमुखी है। विशेष रूप से, मेरे पास MULTILINE_CPP_IS_BRIEF विकल्प चालू है, जो मुझे "संक्षिप्त" विवरण के रूप में लिखने की अनुमति देता है, और फिर रिक्त रेखाओं का उपयोग करके पैराग्राफ में "विवरण" दस्तावेज़ को तोड़ देता है। दूसरे शब्दों में:

/// Changes the active viewing area of the currently selected region. 
/// 
/// The modification is merely enqueued. This function has no effect until the 
/// FlushRegion() function is called. 
/// 
/// Newly-exposed regions will not be repainted automatically. The user must also 
/// call the UpdateRegion() function on these regions to cause their contents to 
/// be redrawn. 
/// 
/// @param dx The amount, in pixels, to shift the visible region horizontally. 
/// @param dy The amount, in pixels, to shift the visible region vertically. 
/// 
/// @remarks 
/// Note that this function is reentrant, but not thread-safe! 
void ScrollRegion(int dx, int dy); 

यह वास्तव में मुझे देता है उत्पादन मैं इच्छा जबकि @brief और \details मैं उपयोग करने के लिए इस तरह शोर मेटा-आदेशों की संख्या नीचे रखे हुए हैं।

समस्या तब आती है जब मैं अपने "टिप्पणी" खंड में दूसरा पैराग्राफ शामिल करने का प्रयास करता हूं, जैसा कि मैंने "विवरण" खंड के लिए (निहित) किया था। उदाहरण के लिए:

/// Changes the active viewing area of the currently selected region. 
/// 
/// The modification is merely enqueued. This function has no effect until the 
/// FlushRegion() function is called. 
/// 
/// Newly-exposed regions will not be repainted automatically. The user must also 
/// call the UpdateRegion() function on these regions to cause their contents to 
/// be redrawn. 
/// 
/// @param dx The amount, in pixels, to shift the visible region horizontally. 
/// @param dy The amount, in pixels, to shift the visible region vertically. 
/// 
/// @remarks 
///  Note that this function is reentrant, but not thread-safe! 
/// 
///  If thread safety is required, the user must handle locking and unlocking 
///  the region manually. 
void ScrollRegion(int dx, int dy); 

उत्पन्न उत्पादन की टिप्पणी के भाग के रूप @remarks खंड में दूसरा पैराग्राफ की व्याख्या नहीं करता है। मैं बता सकता हूं क्योंकि यह HTML आउटपुट में समान स्तर पर इंडेंट नहीं है, और यह XML आउटपुट में <simplesect kind="remark"> टैग के अंतर्गत स्थित नहीं है।

मैंने दूसरे पैराग्राफ की शुरुआत में a @par command जोड़ने का प्रयास किया, लेकिन ऐसा नहीं किया जो मैं चाहता था, या तो। नया अनुच्छेद अभी भी "टिप्पणी" खंड का बच्चा नहीं है। एक्सएमएल आउटपुट में, इसे एक नए <simplesect kind="para"> टैग के अंदर रखा जा रहा है जो मूल <simplesect kind="remark"> टैग का भाई है।

हालांकि इस शोध, मैंने देखा है कि किसी और को दोहराया गया था @remarks आदेश:

/// Changes the active viewing area of the currently selected region. 
/// 
/// The modification is merely enqueued. This function has no effect until the 
/// FlushRegion() function is called. 
/// 
/// Newly-exposed regions will not be repainted automatically. The user must also 
/// call the UpdateRegion() function on these regions to cause their contents to 
/// be redrawn. 
/// 
/// @param dx The amount, in pixels, to shift the visible region horizontally. 
/// @param dy The amount, in pixels, to shift the visible region vertically. 
/// 
/// @remarks 
///  Note that this function is reentrant, but not thread-safe! 
/// @remarks 
///  If thread safety is required, the user must handle locking and unlocking 
///  the region manually. 
void ScrollRegion(int dx, int dy); 

कि उत्पादन है कि मैं इच्छा का उत्पादन करता है। एक्सएमएल आउटपुट में <simplesect kind="remark"> टैग के तहत दोनों पैराग्राफ <para> टैग में घोंसले हुए हैं, और दृश्य आउटपुट HTML आउटपुट में सही है। लेकिन वह बदसूरत है और मुझे गलती की तरह दिखता है।

क्या ऐसा करने का कोई मानक तरीका है जो मुझे याद आ रहा है? निश्चित रूप से मैं अपने दस्तावेज़ के "टिप्पणी" खंड में एकाधिक अनुच्छेदों को प्राप्त करने वाला पहला व्यक्ति नहीं हूं ... और यह @remarks तक सीमित नहीं है; उदाहरण के लिए, @internal के साथ एक ही बात होती है।

मेरे पास डोक्सिजन का नवीनतम संस्करण स्थापित है (1.8.2), लेकिन मुझे बहुत संदेह है कि यह संस्करण-विशिष्ट है।

Answer 1

आपका अंतिम उदाहरण कोड, कि

/// @remarks 
///  Note that this function is reentrant, but not thread-safe! 
/// @remarks 
///  If thread safety is required, the user must handle locking and unlocking 
///  the region manually. 

वास्तव में बहु अनुच्छेद टिप्पणी ब्लॉकों के लिए \remarks की उम्मीद उपयोग है।doxygen manual (जोर मेरा) से:

\remark { remark text }

एक पैरा जहां एक या अधिक टिप्पणी दर्ज किया जा सकता शुरू होता है। अनुच्छेद इंडेंट किया जाएगा। अनुच्छेद के पाठ में कोई विशेष आंतरिक संरचना नहीं है। पैराग्राफ के अंदर सभी दृश्य वृद्धि आदेशों का उपयोग किया जा सकता है। एकाधिक आसन्न \remark आदेश एक अनुच्छेद में शामिल हो जाएंगे। प्रत्येक टिप्पणी एक नई लाइन पर शुरू होगी। वैकल्पिक रूप से, एक \remark कमांड कई टिप्पणियों का उल्लेख कर सकता है। \remark कमांड समाप्त होता है जब रिक्त रेखा या कुछ अन्य सेक्शनिंग कमांड का सामना करना पड़ता है।

तो \remark (और \remarks, जो \remark के रूप में सिर्फ एक ही है) एक पैरा के अंत में समाप्त हो जाती है, लेकिन आसन्न \remark रों एक \remark ब्लॉक बनाने के लिए एक साथ लगाया गया कर दिया जाएगा।

आपको यह कहना सही है कि यह व्यवहार \remarks और \remark तक सीमित नहीं है। एक ही काम करने के लिए कि मैं यहाँ नहीं उल्लेख देखा है ऐसा लगता है कि किसी भी आदेश है कि उदाहरण के लिए एक तर्क के रूप पाठ का एक पैरा लेता है, देखते हैं,, \bug, \todo, \warning आदि

Answer 2

एक समाधान करने के लिए लागू होता है, समाप्त करने के लिए है \ n के साथ आपकी लाइनें। यह उस सफेद स्थान को डालने के दौरान, जो आप देखना चाहते हैं, सब कुछ एक साथ समूहीकृत रखेगा।

यदि आप एक खाली रेखा चाहते हैं, तो सुनिश्चित करें कि ऊपर की रेखा \ n है, और आपके पास \ n इसके साथ एक खाली रेखा है।

अपने उदाहरण में, आप चाहते हैं:

/// @remarks 
///  Note that this function is reentrant, but not thread-safe!\n 
///  \n 
///  If thread safety is required, the user must handle locking and unlocking 
///  the region manually. 

और है कि यह दिखाई के रूप में आप यह दिखाना चाहते हैं बनाना चाहिए।

Answer 3

समाधान सामान्यीकृत किए जा सकते हैं (डॉक्सिजन 1.8.9.1)। मैं प्रयोग किया है:

/// \par Title 
/// text of paragraph 1\n 
/// 
/// text of paragraph 2\n 
/// 
/// ~~~ 
/// Some code/sketch 
/// ~~~ 

kjkAe4Wbasj6 तीन पैराग्राफ दांतेदार कर रहे हैं और शीर्ष लेख Title उनके ऊपर मोटे अक्षरों में छपा है। बेशक, \par Title को \remark के साथ प्रतिस्थापित किया जा सकता है। पैराग्राफ के अंत में जादू वाक्यांश \n है और रिक्त रेखाएं वैकल्पिक रूप से डाली जा सकती हैं। खाली लाइनों में \n की आवश्यकता नहीं है। दुर्भाग्यवश मुझे कोड अनुभाग के बाद इंडेंट टेक्स्ट पैराग्राफ को जोड़ने का कोई तरीका नहीं मिला है।

Answer 4

यदि आपको अपनी बहु-अनुच्छेद टिप्पणियों के लिए अपने स्रोत में एकाधिक @remarks लाइनें पसंद नहीं हैं, तो मुझे लगता है कि आप @parblock & @endparblock का उपयोग कर सकते हैं ताकि एक ही @remark के लिए एकाधिक पैराग्राफ शामिल हो सकें।