डॉक्सिजन के साथ सी ++ टेम्पलेट्स और टेम्पलेट मेटाफंक्शन को कैसे दस्तावेज़ित करें?

Question

क्या कोई दिशा-निर्देश हैं कि सी ++ टेम्पलेट्स और टेम्पलेट मेटा-फ़ंक्शंस को डॉक्सीजन के साथ कैसे दस्तावेज किया जाना चाहिए?

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

/// @brief metafunction for generation of a map of message types to 
/// their associated callbacks. 
/// @tparam Seq the list of message types 
template< class Seq > 
struct generate_callback_map 
{ 
    typedef typename mpl::transform< Seq 
            , build_type_signature_pair<mpl::_1> 
            >::type vector_pair_type; 
    typedef typename fusion::result_of::as_map<vector_pair_type>::type type; 
}; 

अब तक मैं निम्नलिखित सुझाव देखा है:

• @tparam टेम्प्लेट पैरामीटर दस्तावेज़ के लिए इस्तेमाल किया।
• @arg टेम्पलेट पैरामीटर दस्तावेज करने का वैकल्पिक तरीका।
• @brief मेटाफंक्शन का वर्णन करने के लिए उपयोग किया जाता है।

मेटाफंक्शन के लिए 'लौटा प्रकार' कैसे दस्तावेज किया जाना चाहिए?

क्या किसी के पास C++ टेम्पलेट्स के साथ डॉक्सीजन का उपयोग करने के लिए कोई अच्छा सुझाव या व्यक्तिगत वरीयता है?

Answer 1

मुझे नहीं लगता कि यह संभव उपयोग दस्तावेज़ उन्नत टेम्पलेट है, क्योंकि यह मूल रूप से वस्तु उन्मुख प्रतिमान के लिए डिजाइन किया गया था और metaprograming नहीं Doxygen साथ निर्माण करती है। एक उदाहरण के रूप में, जीएनयू एसटीएल (libstdC++) डॉक्सिजन का उपयोग करता है लेकिन एसटीएल में मेटाप्रोग्रामिंग दस्तावेज करने के poor job करता है।

दूसरी ओर, को बढ़ावा देने के लिए अपने स्वयं उपकरणों का उपयोग करता: QuickBook स्टैंडअलोन पाठ फ़ाइलें और Doxygen प्रलेखित स्रोत का उपयोग करता है BoostBook मार्कअप (DocBook के विस्तार), जो बारी-बारी html/पीडीएफ उत्पन्न करता है उत्पन्न करने के लिए। result libstdC++ के मुकाबले अधिक जानकारीपूर्ण है लेकिन स्पष्ट रूप से देव से थोड़ा और काम शामिल है।

चूंकि बूस्ट प्रलेखन तर्कसंगत रूप से मेटाप्रोग्रामिंग के लिए सबसे अच्छा है, इसलिए आप उस मार्ग पर जा सकते हैं, खासकर जब यह डॉक्सिजन पूरा करता है - आप अपने मौजूदा मार्कअप का पुन: उपयोग कर सकते हैं।

हालांकि यह वास्तव में आपके प्रश्न का उत्तर नहीं देता है, तो आपको हालिया क्लैंग developments में रुचि हो सकती है। --with-extra-options=-Wdocumentation के साथ क्लैंग का निर्माण करते समय यह आपके कोड के साथ अपने डॉक्सिजन मार्कअप की जांच करता है और दस्तावेज़ीकरण चेतावनियां उत्पन्न करता है। आपको डॉक्स/कोड सिंक्रनाइज़ रखने के लिए मजबूर करता है।

Answer 2

फ़ंक्शन तर्कों के लिए @tparam टेम्पलेट तर्क, @arg का उपयोग करें। वापसी मूल्यों के लिए, @return। यहां कोई वापसी नहीं है। केवल typedef एस हैं।

बीटीडब्ल्यू, आपका नमूना कोड मेटाफंक्शन की तरह नहीं दिखता है। मेटाफंक्शंस बालों वाले जानवर हैं जो एसएफआईएनएई का लाभ लेते हैं ताकि सी ++ मूल रूप से (उदाहरण के लिए, प्रतिबिंब) का इरादा न हो। आपका generate_callback_map टेम्पलेट टाइपपीफ के लिए बस एक C++ 03 स्टैंड-इन जैसा दिखता है।

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

/// @brief metafunction for generation of a map of message types to 
/// their associated callbacks. 
/// @details 
/// Usage: Use <tt>generate_callback_map<Type>::type</tt> to ... 
/// @tparam Seq the list of message types 
/// 
template< class Seq > 
struct generate_callback_map 
{ 
    /// @brief It's a good idea to document all of your typedefs. 
    typedef typename mpl::transform< Seq 
           , build_type_signature_pair<mpl::_1> 
           >::type vector_pair_type; 

    /// @brief This is why generate_callback_map exists. Document it! 
    typedef typename fusion::result_of::as_map<vector_pair_type>::type type; 
};