निर्भरता गुणों के लिए एक्सएमएल दस्तावेज़ीकरण

Question

एक निर्भरता संपत्ति दस्तावेज करने का सबसे अच्छा तरीका क्या है?

मैं मैदान पर एक्सएमएल प्रलेखन रखना चाहिए:

/// <summary>Documentation goes here</summary> 
public static readonly DependencyProperty NameProperty = 
     DependencyProperty.Register(...) 

या संपत्ति पर:

/// <summary>and/or here?</summary> 
public string Name{ get{...} set{...} } 

या मैं वास्तव में दस्तावेज़ के लिए (और बनाए रखने के) दोनों की आवश्यकता है?

Answer 1

ठीक है, यह वही है जो मैंने साथ आया है।

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

/// <dpdoc /> 
public static readonly DependencyProperty PositionProperty = 
    DependencyProperty.Register(...) 

सी # संपत्ति सामान्य रूप से प्रलेखित की जाती है, बस सुनिश्चित करें कि मूल्य विवरण को न भूलें।

/// <summary>Gets or sets the position of this element</summary> 
/// <value>Position (in pixel) relative to the parent's upper left corner.</value> 
/// <remarks><para> 
/// If either the <c>x</c> or <c>y</c> component is <c>+inf</c> this indicates... 
/// </para></remarks> 
public Point Position{ get{...} set{...} } 

विजुअल स्टूडियो इमारत के दौरान उन टिप्पणियों से एक XML फ़ाइल बनाता है। थोड़ा xsl रूपांतरण के साथ dpdoc नोड को संपत्ति प्रलेखन के एक संशोधित संस्करण द्वारा प्रतिस्थापित किया गया है। परिणामस्वरूप एक्सएमएल फ़ाइल वैसा ही है जैसे हमने अच्छी तरह से संपत्ति पहचानकर्ता को दस्तावेज किया था।

/// <summary>Position (in pixel) relative to the parent's upper left corner.</summary> 
/// <remarks><para> 
/// If either the <c>x</c> or <c>y</c> component is <c>+inf</c> this indicates... 
/// <para> 
/// This dependency property can be accessed via the <see cref="Position"/> property. 
/// </para> 
/// </para></remarks> 
public static readonly DependencyProperty PositionProperty = 
    DependencyProperty.Register(...) 

इस तरह, दोनों एपीआई उचित प्रलेखन है और हम कोड में प्रलेखन नकल करने की जरूरत नहीं है: यह भी एक छोटे नोट चर तक पहुँचने का एक वैकल्पिक तरीका है कि वहाँ भी शामिल है। एक्सएसएल परिवर्तन पोस्ट-बिल्ड इवेंट में किया जा सकता है या दस्तावेज़ीकरण उत्पादन प्रक्रिया में एकीकृत किया जा सकता है।

<?xml version="1.0" encoding="UTF-8"?> 
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> 
    <xsl:template match="//dpdoc"> 
     <xsl:variable name="propertyName" select="concat('P:', substring(../@name,3,string-length(../@name)-10))" /> 
     <summary> 
      <xsl:apply-templates select="//member[@name=$propertyName]/value/node()"/> 
     </summary> 
     <xsl:apply-templates select="//member[@name=$propertyName]/*[not(self::remarks)][not(self::summary)][not(self::value)]"/> 
     <remarks> 
      <xsl:apply-templates select="//member[@name=$propertyName]/remarks/node()"/> 
      <para> 
       This dependency property can be accessed via the 
       <see> 
        <xsl:attribute name="cref"><xsl:value-of select="$propertyName"/></xsl:attribute> 
       </see> 
       property. 
      </para> 
     </remarks> 
    </xsl:template> 
    <xsl:template match="@*|node()"> 
     <xsl:copy> 
      <xsl:apply-templates select="@*|node()"/> 
     </xsl:copy> 
    </xsl:template> 
</xsl:stylesheet> 

मैं क्यों चाहते हैं कि उसे इस तरह से है::

यहाँ XSL है

• दोनों संपत्ति पहचानकर्ता (DependencyProperty उदाहरण) और संपत्ति, सार्वजनिक होते हैं और इसलिए कर सकते हैं कानूनी रूप से संपत्ति का उपयोग करने के लिए इस्तेमाल किया जा रहा है। हमारे पास एक ही लॉजिकल चर के लिए दो एपीआई हैं।
• कोड प्रलेखन का वर्णन करना चाहिए कि पहले से मौजूद नहीं है। इस संदर्भ में इसे संपत्ति के अर्थ और उसके मूल्य और इसका सही तरीके से उपयोग करने का अर्थ वर्णन करना चाहिए। चूंकि, दोनों संपत्ति पहचानकर्ता और सी # संपत्ति, समान तार्किक चर का संदर्भ देते हैं, उनके समान अर्थ हैं।
• उपयोगकर्ता तार्किक चर का उपयोग करने के दो तरीकों में से एक को स्वतंत्र रूप से चुन सकता है, और दूसरे के बारे में जागरूक नहीं है। हजारों दोनों को सही ढंग से दस्तावेज किया जाना चाहिए।
• कॉपी-पेस्टिंग कोड टिप्पणियां प्रतिलिपि कोड के रूप में उतनी ही खराब हैं।

Answer 2

आपको दोनों को दस्तावेज और बनाए रखना चाहिए। एक निर्भरता संपत्ति है, दूसरा एक नियमित संपत्ति है जो उस निर्भरता संपत्ति तक पहुंच के रूप में लागू की जाती है। वे एक ही बात नहीं हैं और अलग-अलग दस्तावेज की आवश्यकता है।