स्रोत कोड को XML दस्तावेज़ का एक हिस्सा कैसे बनाएं और DRY का उल्लंघन न करें?

Question

मैं XML दस्तावेज़ में स्रोत कोड के कुछ हिस्सों को जोड़ना चाहता हूं।

/// <summary> 
/// Says hello world in a very basic way: 
/// <code> 
/// System.Console.WriteLine("Hello World!"); 
/// System.Console.WriteLine("Press any key to exit."); 
/// System.Console.ReadKey(); 
/// </code> 
/// </summary> 
static void Main() 
{ 
    System.Console.WriteLine("Hello World!"); 
    System.Console.WriteLine("Press any key to exit."); 
    System.Console.ReadKey(); 
} 

इस बनाए रखने दर्दनाक हो जाएगा: मैं कुछ < कोड को > तत्वों, इस तरह & पेस्ट स्रोत कोड की नकल कर सकता है। क्या सी # में एक्सएमएल दस्तावेज में स्रोत कोड जोड़ने की अन्य संभावनाएं हैं?

मैं एक्सएमएल दस्तावेज को सैंडकासल के साथ संसाधित कर रहा हूं और इसमें से एक तकनीकी सहायता फ़ाइल (* .chm) बनाना चाहता हूं। मैं उस सहायता फ़ाइल में भागों या पूर्ण विधि निकायों को जोड़ना चाहता हूं।

---

संपादित करें: slide_rule से टिप्पणी के लिए धन्यवाद।

public decimal CalculateFee(Bill bill) 
{ 
    if (bill.TotalSum < 5000) return 500; 
    else 
    { 
     if (bill.ContainsSpecialOffer) return bill.TotalSum * 0.01; 
     else return bill.TotalSum * 0.02; 
    } 
} 

यह शुल्क तकनीकी में गणना के तरीके के बारे में जानकारी को जोड़ने के लिए एक संभावना है करने के लिए अच्छा होगा:

मान लीजिए मैं इस तरह कुछ विधि है: मैं एक और अधिक यथार्थवादी और कम तुच्छ उदाहरण जोड़ लिया है मदद फ़ाइल

सबसे स्पष्ट समाधान एल्गोरिदम को टिप्पणी में समसामयिक पाठ के रूप में लिखना होगा: "यदि बिल की कुल राशि 5000 से कम है तो ..."।

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

दोनों समाधान DRY सिद्धांत का उल्लंघन करते हैं! मैं जानकारी फ़ाइल में विधि निकाय के बिना विधि निकायों या विधि निकाय के टुकड़े जोड़ना चाहता हूं।

क्या यह सी # में संभव है? (मुझे लगता है कि रूबी के लिए RDoc ऐसा करने में सक्षम है, लेकिन मैं सी # में कुछ समाधान की जरूरत है)

Answer 1

बस वहाँ बाहर एक विचार फेंक ...

एक प्रक्रिया है कि किसी तरह से सीमांकित कोड ब्लॉक के लिए लग रहा है स्वचालित, फिर उस कोड को एक्सएमएल टिप्पणी में इंजेक्ट करें।

/// <summary> 
/// Says hello world in a very basic way: 
/// <code> 
///  Code block 1 
/// </code> 
/// </summary> 
static void Main() 
{ 
    // Code block 1 start 
    System.Console.WriteLine("Hello World!"); 
    System.Console.WriteLine("Press any key to exit."); 
    System.Console.ReadKey(); 
    // Code block 1 end 
} 

मुझे पता है कि यह सुंदर नहीं है, लेकिन यह एक शुरुआत है! ;)

Answer 2

क्यों

<summary> 
    <description>Displays Hello World!</description> 
    <arguments>None</arguments> 
    <returns>None</returns> 
</summary> 

बस एक विचार जैसे क्षेत्रों का उपयोग करके कोड का दस्तावेजीकरण के लिए एक अधिक मानक दृष्टिकोण के साथ नहीं जाना।

Answer 3

मेरे लिए टिप्पणियों का मुख्य उद्देश्य कोड का वर्णन करना है। कोड की प्रतिलिपि बनाना और पेस्ट करना उस उद्देश्य को पूरा नहीं करेगा, इसलिए मुझे लगता है कि मेरा प्रश्न "दस्तावेज़ीकरण का उद्देश्य क्या है?" क्या आप दस्तावेज करना चाहते हैं कि विधि + (एपीआई दस्तावेज की तरह) को कॉल करने वाले किसी व्यक्ति के लिए विधि क्या है या क्या आपको यह दस्तावेज करना है कि विधि कैसे काम करती है ताकि कोई अन्य डेवलपर स्रोत कोड बनाए रख सके? या कुछ अलग है?

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

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

Answer 4

आप include element के साथ खेलना चाह सकते हैं। मैंने इसका कभी भी उपयोग नहीं किया है, इसलिए मुझे नहीं पता कि आप उस तत्व को दूसरे, नियमित XML टिप्पणी तत्वों के साथ मिश्रित कर सकते हैं, लेकिन जिस तरह से मैंने (स्पैस) दस्तावेज़ पढ़ा है, ऐसा नहीं लगता है।

हालांकि यह संभव नहीं है, भले ही यह संभव नहीं है, हो सकता है कि आप उस तत्व के उपयोग को उस स्क्रिप्ट के साथ जोड़ सकें जो कोड के प्रासंगिक टुकड़े पाता है और इसे XML फ़ाइल में सम्मिलित करता है।

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

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

आप सहायता फ़ाइल में जाने के लिए कोड की पहचान कैसे करेंगे? मेरे सिर के ऊपर से, मैं तीन विकल्प के बारे में सोच सकते हैं:

• गुण
• क्षेत्र
• टिप्पणियाँ

व्यक्तिगत रूप से, मैं गुण पसंद करेंगे।

एक बंद टिप्पणी मैं बाहर बात करने के लिए है कि जब तक यह निश्चित रूप से संभव है, यह सिर्फ प्रतिलिपि करने और चिपकाने और अनुशासन :) का एक सा रखने की तुलना में शायद और अधिक काम है करना चाहते हैं पर