उच्च गुणवत्ता वाले प्रलेखन एक सफल सॉफ्टवेयर उत्पाद का एक अभिन्न अंग है। एक कार्यक्रम और एक सॉफ्टवेयर घटक के सभी कार्यों और क्षमताओं का एक पूर्ण और समझने योग्य विवरण बनाने के लिए बहुत प्रयास और धैर्य की आवश्यकता होती है। इस लेख में, मैं .NET घटकों के लिए प्रलेखन बनाने के कुछ व्यावहारिक पहलुओं पर चर्चा करूंगा।
मान लीजिए कि हमारे पास तैयार या लगभग तैयार डेवलपर्स के लिए कुछ .NET लाइब्रेरी है (वे भी अंतिम उपयोगकर्ता हैं)। लाइब्रेरी API त्रुटिहीन है, बग्स की संख्या प्रभावशाली रूप से छोटी है, और वास्तव में यह लाइब्रेरी नहीं है, लेकिन केवल सही कोड का एक भंडार है। बिंदु छोटा है - उपयोगकर्ताओं को यह समझाने के लिए कि इस अद्भुत उत्पाद के साथ कैसे काम किया जाए।
लेखन दस्तावेज के लिए अलग-अलग दृष्टिकोण हैं। कुछ टीम उत्पाद निर्माण की शुरुआत में दस्तावेज बनाना शुरू करना पसंद करती हैं। दूसरों ने काम खत्म करने के लिए मैनुअल लिखना स्थगित कर दिया। कुछ टीमों में, प्रलेखन ऐसे विशेष लोगों द्वारा लिखा जाता है जो डेवलपर से डेवलपर और प्रबंधक से प्रबंधक तक, उत्पाद के बारे में ज्ञान जमा करते हैं। कई छोटी टीमों में ऐसे विशेष लोग नहीं होते हैं, यही वजह है कि प्रलेखन अक्सर डेवलपर या डेवलपर्स द्वारा लिखा जाता है। कोई व्यक्ति मदद और नियमावली जैसे तीसरे पक्ष के उपकरण का उपयोग करता है, जिसमें, वास्तविक जीवन के पाठ संपादक के रूप में, आप एक बहुत ही जटिल लेआउट बना सकते हैं और आउटपुट पर विभिन्न स्वरूपों में प्रलेखन प्राप्त कर सकते हैं। कई लोग एक अलग दृष्टिकोण का उपयोग करते हैं, व्यापक रूप से हाल ही में पदोन्नत - सीधे कार्यक्रम / पुस्तकालय कोड में प्रलेखन लेखन।
अपने काम में मैंने थर्ड-पार्टी टूल्स और बिल्ट-इन दोनों का इस्तेमाल किया। उन्होंने तुरंत और अंतिम समय में दोनों के लिए दस्तावेज लिखना शुरू किया। परिणामस्वरूप, मैंने अपने लिए निर्णय लिया कि उत्पाद के निर्माण की दूसरी छमाही में दस्तावेज लिखना शुरू करना बेहतर है, पूरा होने के करीब, एपीआई, सुविधाओं के सेट आदि को स्थिर करने के लिए, जिसका अर्थ है कि प्रलेखन को अक्सर समायोजित करना होगा। कोड में सीधे दस्तावेज़ीकरण लिखना भी अंततः तीसरे पक्ष के कार्यक्रमों की तुलना में अधिक सुविधाजनक निकला, हालांकि पहली बार में यह बिल्कुल विपरीत लग रहा था। यह लेख सिर्फ प्रलेखन को सीधे कोड में लिखने का तरीका है।
हम एपीआई का वर्णन करते हैं
कंपाइलर C # और VB.NET एक विशेष तरीके (xml टिप्पणियाँ) में स्वरूपित टिप्पणियों को पहचान सकते हैं और, यदि आवश्यक हो, तो एक xml फ़ाइल बनाएँ जिसे तब दस्तावेज़ बनाने के लिए उपयोग किया जा सकता है। इस अवसर का लाभ उठाने के लिए, सभी सार्वजनिक वर्गों और xml टिप्पणियों का उपयोग करने के तरीकों का वर्णन करना आवश्यक है। यह कुछ इस तरह दिखता है:
/// <सारांश>
/// ABGR मान से R घटक प्राप्त करता है
/// <cref = "O: BitMiracle.LibTiff.Classic.Tiff.ReadRGBAImage"> ReadRGBAImage </ see> देखें।
/// </ सारांश>
/// <परम नाम = "abgr"> ABGR मूल्य। </ param>
/// <रिटर्न> एबीजीआर मूल्य से आर घटक। </ रिटर्न>
सार्वजनिक स्थैतिक int GetR ( int abgr )
{
वापसी ( abgr & 0xff ) ;
}
डिफ़ॉल्ट रूप से, टिप्पणियों से xml फ़ाइल बनाना अक्षम है। आपको बिल्ड टैब पर प्रोजेक्ट गुण में इसे सक्षम करने की आवश्यकता है।
परिणामस्वरूप, संकलन के दौरान, आपके असेंबली की फ़ाइल के अलावा, एक xml-file उत्पन्न होगी जिसमें कोड से सभी xml-comments (गैर-सार्वजनिक संरचनाओं पर टिप्पणी सहित) शामिल हैं। यह फ़ाइल अपने आप में इस लिए उपयोगी है कि यदि आप इसे असेंबली (अपने dll) के बगल में रखते हैं, तो यह IntelliSense फंक्शन में विजुअल स्टूडियो में उपयोगकर्ता को कोड टाइप करने के तरीकों के लिए विवरण प्रदर्शित करने की अनुमति देगा। यहाँ एक उदाहरण दिया गया है कि यह ऊपर दिखाए गए GetR फ़ंक्शन के लिए कैसा दिखेगा:
हालाँकि, ज्यादातर मामलों में, उत्पन्न xml फ़ाइल में आंतरिक संरचनाओं पर टिप्पणियां होती हैं जिन्हें उपयोगकर्ताओं की आवश्यकता नहीं होती है या वे देख नहीं सकते हैं। नीचे मैं लिखूंगा कि xml-file को स्वचालित रूप से कैसे साफ़ करें ताकि इसमें केवल सार्वजनिक विधियों का वर्णन हो।
मैं सभी एक्सएमएल टैग पर विस्तार से विचार नहीं करूंगा, लेकिन बस सबसे अधिक इस्तेमाल किए जाने वाले लोगों का संक्षेप में वर्णन करने की कोशिश करता हूं।
सारांश टैग का उपयोग किसी वर्ग, इंटरफ़ेस, enum, विधियों और गुणों के वर्ग या इंटरफ़ेस, और गणना सदस्यों के उद्देश्य का संक्षेप में वर्णन करने के लिए किया जाता है। परम टैग आपको फ़ंक्शन द्वारा स्वीकृत पैरामीटर का वर्णन करने की अनुमति देता है। यह टैग प्रत्येक स्वीकृत पैरामीटर के लिए उपयोग किया जाना चाहिए। किसी फ़ंक्शन के रिटर्न मान का वर्णन करने के लिए रिटर्न टैग का उपयोग किया जाता है। मूल्य टैग कुछ मूल्य लेने और / या रिटर्न करने वाले मूल्य का वर्णन करने के लिए उपयोगी है। एक मायने में, मूल्य टैग रिटर्न टैग का एक एनालॉग है।
/// <सारांश>
/// फ़ॉन्ट एसेंट हो जाता है।
/// </ सारांश>
/// <value> फ़ॉन्ट चढ़ता है। </ value>
/// <टिप्पणी> चढ़ाई बेसलाइन के ऊपर अधिकतम ऊंचाई है
/// ग्लिफ़ द्वारा इस फ़ॉन्ट में, ग्लिफ़ की ऊँचाई को छोड़कर
/// उच्चारण वर्ण। </ टिप्पणी>
सार्वजनिक छोटी चढ़ाई
{
प्राप्त
{
वापसी Impl। चढ़ाई;
}
}
बहुत उपयोगी (और, दुर्भाग्य से, अक्सर अनदेखा किया गया) टिप्पणी टैग है, जो आपको वर्णित इकाई के लिए नोट्स निर्दिष्ट करने की अनुमति देता है। गणना के सदस्यों के विवरण को छोड़कर इस टैग का उपयोग लगभग हर जगह किया जा सकता है। वास्तव में, यह गणना करने वाले सदस्यों के लिए भी संभव है, लेकिन vs2005 की शैली में जारी किए गए दस्तावेज में, ये नोट बस दिखाई नहीं देंगे, जिससे इस तरह के नोटों की उपयोगिता कम हो जाती है।
मैं कुछ और व्यावहारिक नोट / सिफारिशें दूंगा।
डाउनलोड करें और GhostDoc नामक Visual Studio के लिए एक्सटेंशन इंस्टॉल करें। यह एक्सटेंशन सभी स्टूडियो संस्करणों (संस्करण 2005 से शुरू) में काम करता है और xml टिप्पणियों के निर्माण को बहुत सरल करता है। Ctrl-Shift-D दबाकर, यह एक्सटेंशन उस इकाई का विवरण सम्मिलित करता है, जिस पर वर्तमान में कर्सर स्थित है। सभी आवश्यक टैग डाले गए हैं, और एक विवरण पाठ आधारित है, उदाहरण के लिए, विधि के नाम और इसके मापदंडों के नाम पर। अक्सर यह केवल उत्पन्न पाठ को समायोजित और पूरक करने के लिए रहता है।
कोड में सीधे दस्तावेज लिखने का नुकसान यह है कि कोड की तुलना में कभी-कभी अधिक टिप्पणियां होती हैं, जिससे कोड को पढ़ना बहुत मुश्किल हो सकता है। इस समस्या को दरकिनार करने के लिए, सार्वजनिक इंटरफ़ेस और कार्यान्वयन को पूरी तरह से अलग करना बहुत सुविधाजनक है।
यदि आपके पास कई अतिभारित विधियाँ हैं, तो उनके लिए दस्तावेज बनाते समय एक अलग पृष्ठ बनाया जाएगा ( यहाँ इस तरह के पृष्ठ का एक उदाहरण है )। इस पृष्ठ के लिए पाठ को अतिभारित टैग में एक अतिभारित विधियों के विवरण में निर्दिष्ट किया जाना चाहिए।
/// <सारांश>
/// फ़ॉन्ट बाइट्स को निर्दिष्ट स्ट्रीम में सहेजता है।
/// </ सारांश>
/// <परम नाम = "स्ट्रीम"> स्ट्रीम बाइट्स को बचाने के लिए स्ट्रीम। </ param>
/// <अधिभार> फ़ॉन्ट बाइट्स को फ़ाइल या स्ट्रीम में सहेजता है। </ ओवरलोड>
सार्वजनिक शून्य सहेजें ( स्ट्रीम स्ट्रीम )
{
Impl। बचा ( धारा ) ;
}
यदि आप एक विधि के विवरण में किसी अन्य विधि या प्रकार का संदर्भ देना चाहते हैं, तो आपको एक निर्माण का उपयोग करने की आवश्यकता है जैसे
<see cref="X:MEMBER"> </see>
, जहाँ X एक वैकल्पिक उपसर्ग है जो इकाई के प्रकार को दर्शाता है (वर्ग के लिए T) , विधि के लिए एम, संपत्ति के लिए पी, ओवरलोड विधियों के समूह के लिए ओ), और सदस्य इकाई का पूर्ण या आंशिक विनिर्देश है। एक आंशिक विनिर्देश और एक लापता उपसर्ग का उपयोग किया जा सकता है, उदाहरण के लिए, एक ही वर्ग के दो तरीकों के बीच या एक ही नामस्थान की दो संस्थाओं के बीच के लिंक के लिए।
आंशिक विनिर्देश (PdfFontEmbedStyle) का उपयोग करने का एक उदाहरण PdfFont के समान नामस्थान में है:
सार्वजनिक सील वर्ग PdfFont
{
...
/// <सारांश>
/// हो जाता है या सेट करता है <see cref = "PdfFontEmbedStyle" /> मान जो निर्दिष्ट करता है
/// यह फॉन्ट दस्तावेज़ में कैसे एम्बेड किया गया है।
/// </ सारांश>
/// <value> <cref = "PdfFontEmbedStyle" /> मान जो निर्दिष्ट करता है
/// इस फॉन्ट को डॉक्यूमेंट में कैसे एम्बेड किया जाता है। </ value>
सार्वजनिक PdfFontEmbedStyle एंबिसल
{
प्राप्त
{
वापसी Impl। EmbedStyle;
}
सेट
{
Impl। एंबिसल = मान ;
}
}
}
यदि आप किसी अन्य नाम स्थान से, अतिभारित विधियों के समूह के लिए, या अतिभारित विधियों के समूह से किसी विशिष्ट विधि का उल्लेख कर रहे हैं, तो आपको पूर्ण विनिर्देश का उपयोग करना चाहिए। पूर्ण विनिर्देशन के उदाहरण:
- संपत्ति का संदर्भ
<see cref="P:System.Exception.HResult"/>
- विधि संदर्भ
<see cref="M:BitMiracle.LibTiff.Classic.Tiff.GetR(System.Int32)"/>
- अतिभारित तरीकों के एक समूह के लिए लिंक
<see cref="O:BitMiracle.LibTiff.Classic.Tiff.PrintDirectory"/>
- वर्ग का संदर्भ
<see cref="T:BitMiracle.LibTiff.Classic.TiffTagMethods"/>
जैसा कि आप देख सकते हैं, पूर्ण विनिर्देश भी विधि के मापदंडों को इंगित करता है, जो आपको लिंक की विशिष्ट पहचान करने की अनुमति देता है, लेकिन लिंक के लेखन को जटिल बनाता है। आप पहले से संकलित xml फ़ाइल से पूर्ण विनिर्देशों की प्रतिलिपि बनाकर मैन्युअल श्रम को बचा सकते हैं।
अतिभारित तरीकों के एक समूह के लिंक के साथ, एक उपद्रव जुड़ा हुआ है। विजुअल स्टूडियो को
O:XXX.YYY
लिए ऐसे लिंक की आवश्यकता होती है, जबकि
O:XXX.YYY
हेल्प फ़ाइल बिल्डर को
Overload:XXX.YYY
होने के लिए ऐसे लिंक की आवश्यकता होती है
Overload:XXX.YYY
। इस समस्या को हल करने के लिए, मैं एक सरल स्क्रिप्ट का उपयोग करता हूं जिसे पोस्ट-बिल्ड इवेंट पर कहा जाता है और
O:
को
Overload:
साथ
Overload:
xml फ़ाइल में बदल देता है, जो काफी मुस्कराता है।
अपने प्रलेखन के कुछ बाहरी लेख (एपीआई विवरण से संबंधित नहीं) या इंटरनेट पर कुछ संसाधन से लिंक करने के लिए, href विशेषता के साथ अच्छे पुराने
<a>
टैग का उपयोग करें। उदाहरण के लिए,
<a href = "54cbd23d-dc55-44b9-921f-3a06efc2f6ce.htm"> </a>
या
<a href = "http://site.com/page.html"> </a>
पहले उदाहरण में, एक बाहरी लेख के साथ दस्तावेज़ का नाम "TOPIC_ID.htm" के रूप में प्रस्तुत किया गया है। विषय आईडी पर बाद में चर्चा की जाएगी।
आप इन लेखों में xml टिप्पणियों का उपयोग करते हुए दस्तावेज़ कोडिंग के बारे में अधिक गहराई से पढ़ सकते हैं:
- प्रलेखन टिप्पणियाँ (C # प्रोग्रामिंग गाइड) के लिए अनुशंसित टैग
msdn.microsoft.com/en-us/library/5ast78ax.aspx - XML प्रलेखन टिप्पणियाँ गाइड
www.dynicity.com/products/XMLDocComments.aspx - XML दस्तावेज़ C # में
habrahabr.ru/blogs/net/41514 - C # और XML स्रोत कोड प्रलेखन
www.codeproject.com/KB/XML/csharpcodedocumentation.aspx?msg=1679454
प्रलेखन फ़ाइल उत्पन्न करें
एक बार आपके घटक का xml विवरण तैयार हो जाने के बाद, आप दस्तावेज़ फ़ाइल उत्पन्न कर सकते हैं। मैं इसके लिए Sandcastle + Sandcastle Help File Builder (SHFB) बंडल का उपयोग करना पसंद करता हूं। मुझे लगता है कि कुछ DocProject पसंद करते हैं। इसकी आवश्यकता है:
- सैंडकैसल को डाउनलोड और इंस्टॉल करें
sandcastle.codeplex.com - सैंडकैसल हेल्प फ़ाइल बिल्डर को डाउनलोड और इंस्टॉल करें
shfb.codeplex.com - सैंडकास्टल द्वारा उपयोग की जाने वाली शैलियों के लिए पैच को डाउनलोड करें और लागू करें
sandcastlestyles.codeplex.com - यदि आपको HTML सहायता प्रारूप में प्रलेखन की असेंबली में कोई समस्या है, तो आपको यह जांचने की आवश्यकता है कि itircl.dll सिस्टम में मौजूद है और पंजीकृत है। आमतौर पर यह dll System32 में निहित है, इसे regsvr32 के माध्यम से पंजीकृत करने की आवश्यकता है। अधिक विवरण यहां लिखे गए हैं:
frogleg.mvps.org/helptechnologies/htmlhelp/hhtips.html#hhc6003
हम chm फॉर्मेट में डॉक्यूमेंट असेंबल करना शुरू करते हैं। ऐसा करने के लिए, सैंडकास्टल हेल्प फ़ाइल बिल्डर चलाएं और प्रोजेक्ट गुण कॉन्फ़िगर करें। "ComponentConfigurations" गुण में, आप असेंबली के दौरान उपयोग किए जाने वाले अतिरिक्त घटकों को कॉन्फ़िगर कर सकते हैं। यदि आपको नहीं पता कि आपको किन घटकों की आवश्यकता हो सकती है, तो आप सभी घटकों का चयन कर सकते हैं। किसी भी मामले में, मैं सुझाव देता हूं कि आप हमेशा इंटेलीजेंसी घटक का उपयोग करें, क्योंकि यह स्वचालित रूप से इनपुट xml फ़ाइल की एक प्रति बनाता है, जो सभी गैर-सार्वजनिक टिप्पणियों से साफ़ हो जाती है। यह इस घटक का परिणाम है जो उपयोगकर्ताओं को दिए जाने की आवश्यकता है, न कि xml फ़ाइल जिसे कंपाइलर बनाएगा।
मैं निम्नलिखित गुणों को तुरंत बदलने की भी सलाह देता हूं:
- बिल्ड सेक्शन: फ्रेमवर्क
- सहायता फ़ाइल अनुभाग: CopyrightHref, CopyrightText, FeedbackEMailAddress, FeedbackEMailLinkText, HelpTitle, HtmlHelpName
- अनुभाग पथ: OutputPath
अगला, प्रोजेक्ट एक्सप्लोरर विंडो में, दस्तावेज़ स्रोत जोड़ें। मैं इसके लिए टिप्पणियों के साथ एक विशिष्ट असेंबली और एक xml फ़ाइल चुनने की सलाह देता हूं, न कि C # / VB.NET प्रोजेक्ट फ़ाइल की। यदि आप एक प्रोजेक्ट फ़ाइल का चयन करते हैं, तो कभी-कभी इस तथ्य के साथ एक समस्या होती है कि दस्तावेज़ में xml टिप्पणियों में परिवर्तन प्रतिबिंबित नहीं होते हैं। इसके लिए किसे दोषी ठहराया जाए, मुझे नहीं पता।
एक और महत्वपूर्ण कदम SHFB में नाम स्थान का वर्णन करना है। कोड में Xml टिप्पणियाँ नेमस्पेस के लिए काम नहीं करती हैं, इसलिए आपको इसे मैन्युअल रूप से करने की आवश्यकता है। इसमें टिप्पणी अनुभाग और NamespaceSummaries संपत्ति यहां मदद करेगी। नामस्थान के विवरण में आप मानक html टैग का उपयोग कर सकते हैं।
प्रोजेक्ट सेटअप पूरा हो गया है, यह .hm फ़ाइल बनाने का समय है। प्रलेखन चुनें-> प्रोजेक्ट बनाएँ, और यदि सब कुछ सही ढंग से किया गया था, तो हमें MSDN की शैली में एक सुंदर प्रलेखन फ़ाइल मिलती है।
विषय पर उपयोगी लिंक:
- SHFB सेटिंग्स का विस्तृत विवरण
www.codeproject.com/KB/cs/SandcastleBuilder.aspx - हबराबर पर SHFB की समीक्षा
habrahabr.ru/blogs/net/68227 - Sandcastle और DocProject की तुलना
stackoverflow.com/questions/319632/docproject-vs-sandcastle-help-file-builder-gui
लेख लिखना
हालाँकि, वहाँ रुकना नहीं है - आपके घटक का एक एकल एपीआई विवरण पूर्ण प्रलेखन के लिए पर्याप्त नहीं है। अच्छे प्रलेखन में आमतौर पर अतिरिक्त लेख, उदाहरण, एफएक्यू आदि शामिल होते हैं।
प्रोजेक्ट एक्सप्लोरर विंडो में, एक नया कंटेंट लेआउट एलिमेंट जोड़ें - यह एक डॉक्यूमेंट में शामिल किए जाने के संबंध में एक विवरण (सापेक्ष स्थिति के संकेत के साथ) है। सामग्री लेआउट विंडो नए विषय जोड़ता है। प्रत्येक लेख MAML प्रारूप (.aml फ़ाइलों) में वर्णित है, यह एक xml- आधारित प्रारूप है। सैंडकास्टल हेल्प फाइल बिल्डर पूर्वनिर्धारित टेम्पलेट्स के एक सेट के साथ आता है, जो लेख लिखने में पदार्पण को सरल बनाता है। मैं मुख्य रूप से वैचारिक टेम्पलेट का उपयोग करता हूं, कम सामान्यतः वॉकथ्रू ।
प्रत्येक लेख का वर्णन विषय आईडी से शुरू होता है - एक अद्वितीय पहचानकर्ता। इस पहचानकर्ता के आधार पर, एक html फ़ाइल बनाई जाती है, जो बाद में chm में आ जाती है। उत्पन्न HTML फ़ाइल को "TOPIC_ID.htm" नाम दिया गया है। इस विषय आईडी का उपयोग कोड के अन्य लेखों या xml टिप्पणियों के लेखों के लिंक के लिए भी किया जाता है।
एक लेख बनाते समय, इसे "TOPIC_ID.aml" नाम वाली फ़ाइल में सहेजना प्रस्तावित है। बनाते समय, आपको फ़ाइल के सामान्य नाम को तुरंत इंगित करना चाहिए।
SHFB में कुछ नियंत्रणों पर विचार करें जो लेख संपादित करते समय उपयोगी होते हैं।
| दस्तावेज़ का प्रारंभ पृष्ठ सेट करता है (जब प्रदर्शित किया जाएगा
दस्तावेज़ खोलना। |
| वह स्थिति सेट करता है जिसमें एपीआई विवरण डाला जाएगा।
xml फ़ाइल से उत्पन्न। किस विकल्प के आधार पर, एपीआई विवरण डाला जाएगा या तो पहले या बाद में, या इस के एक बच्चे के रूप में तत्व। |
| वर्तमान लेख का पूर्वावलोकन करें।
|
| प्रलेखन में लेख के लिए लिंक डालें। में विषय आईडी का उपयोग करें
पते के रूप में। |
| लेख मार्कअप के लिए मानक टैग डालें।
|
इकाई संदर्भ विंडो (दाईं ओर स्थित) का उपयोग फ़ंक्शन / विधियों के विवरण के लिंक जोड़ने के लिए किया जा सकता है। कोड से निकाय। लिंक डालने का यह तरीका मेरी राय में बहुत सुविधाजनक नहीं है, क्योंकि आपको पहले लेख का पाठ खोलना होगा, फिर इकाई संदर्भ विंडो को खोलना होगा, फिर इस विंडो में भाग या इकाई का पूरा नाम लिखना होगा, फिर सूची में वांछित रेखा ढूंढें और उस पर डबल-क्लिक करें। यह सब इस तथ्य को जन्म देगा कि कर्सर स्थिति पर लिंक लेख में डाला गया है। मैं अपने हाथों से लिंक लिखना पसंद करता हूं, और बिल्ड लॉग में लिंक के लिए पाठ ढूंढता हूं (पिछले बिल्ड से लॉग एक पाठ संपादक में खोला जा सकता है)।
लेख में कोड डालने के लिए,
<code>
उपयोग करें। उदाहरण के लिए:
< कोड भाषा = "सीएस" >
निजी शून्य helloWorld ( )
{
कंसोल। राइटलाइन ( "हैलो वर्ल्ड ! " ) ;
}
</ code >
चित्र सम्मिलित करने के लिए, निम्नलिखित करें:
- प्रोजेक्ट एक्सप्लोरर विंडो में, जोड़ें, फिर मौजूदा आइटम का चयन करें और वांछित चित्र का चयन करें।
- जोड़ी गई फ़ाइल के गुणों में, BuildAction to Image और ImageId गुण को एक सुविधाजनक नाम में बदलें (इसका उपयोग इस छवि के लिंक में किया जाएगा)।
इसके अलावा, आप लेख में छवि का उपयोग इस प्रकार कर सकते हैं:
<मीडियालिंक> <छवि xlink: href = "इमेजआईड" प्लेसमेंट = "केंद्र" / > < / मीडियालिंक>
दुर्भाग्य से, SHFB के वर्तमान संस्करण में, संपादक एकदम सही है। उदाहरण के लिए, टैग स्वचालित रूप से बंद नहीं होते हैं, माउस के साथ बहुत सारी क्रियाएं करनी होती हैं (कोई हॉटकी नहीं होती हैं), सभी मानक टैग में टूलबार पर संबंधित तत्व नहीं होते हैं। विरोधाभासी रूप से, अमल के साथ अधिकांश कार्यों के लिए विजुअल स्टूडियो का उपयोग करना मेरे लिए अधिक सुविधाजनक है। बेशक, आप लेख लिखने के लिए किसी अन्य सुविधाजनक xml-editor का उपयोग कर सकते हैं।
मैंने प्रलेखन के लिए लेख लिखते समय बुनियादी जरूरतों के समाधान का वर्णन किया। यदि आप विषय का बेहतर अध्ययन करना चाहते हैं, तो मैं निम्नलिखित लिंक सुझाता हूं:
- MAML प्रारूप अवलोकन
davesexton.com/blog/blogs/blog/archive/2008/05/24/maml-migration-the-next-step-in-the-evolution-of-help-authoring.aspx - एमएएमएल प्रारूप का विस्तृत विवरण
sandcastlestyles.codeplex.com/releases/view/17333 - SHFB का उपयोग करके प्रलेखन के विभिन्न उदाहरण
www.codeproject.com/KB/winhelp/SandcastleConceptual.aspx - HTML से लेख कैसे बनाएं, MAML नहीं
habrahabr.ru/blogs/net/68227 - प्रलेखन में वर्ग आरेख कैसे एम्बेड करें
habrahabr.ru/blogs/net/73790
निर्माण प्रक्रिया में एकीकरण
आप प्रोजेक्ट फ़ाइल (* .shfbproj) को सैंडकास्टल हेल्प फ़ाइल बिल्डर से विज़ुअल स्टूडियो समाधान में शामिल कर सकते हैं, हालाँकि, फिलहाल इसे पूर्ण प्रोजेक्ट के रूप में उपयोग करने का कोई तरीका नहीं है। यही है, आप ऐसी परियोजना की सामग्री नहीं देख सकते, परियोजना केवल समाधान आइटम समूह में जोड़ी जाएगी।
जोड़ना निम्नानुसार किया जाता है:
- समाधान के लिए, जोड़ें-> मौजूदा आइटम ..., प्रलेखन परियोजना जोड़ें। इसे सॉल्यूशन आइटम फ़ोल्डर में जोड़ा जाएगा।
- जोड़े गए आइटम पर राइट-क्लिक करें और खोलें के साथ चुनें ... खुलने वाले संवाद में, "सैंडकास्टल हेल्प फ़ाइल बिल्डर जीयूआई" जोड़ें और इसे डिफ़ॉल्ट संपादक के रूप में सेट करें।
उसके बाद, विज़ुअल स्टूडियो से प्रलेखन परियोजना को खोला जा सकता है।
कमांड लाइन से बिल्डिंग प्रलेखन अधिक उपयोगी है। इस तरह की विधानसभा पोस्ट-बिल्ड इवेंट या अन्य मामलों में की जा सकती है। कमांड लाइन से प्रलेखन इकट्ठा करना निम्न कमांड के साथ बहुत सरल है:
%SystemRoot%\Microsoft.NET\Framework\v3.5\MSBuild.exe" /p:Configuration=Release Help.shfbproj
इस लाइन पर, Help.shfbproj प्रलेखन परियोजना का नाम है।
मुझे उम्मीद है कि यह लेख आपको अपनी परियोजनाओं के लिए प्रलेखन लिखना शुरू करने में मदद करता है (यदि आप पहले से ऐसा नहीं कर रहे हैं) जिसके लिए आपके उपयोगकर्ता शायद आपको धन्यवाद देंगे। लेखन दस्तावेज में शुभकामनाएँ!