XML相關屬性文檔

Question

什麼是文檔依賴屬性的最佳方式？

我應該把賽場上的XML文檔：

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

或對物業：

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

還是我真的需要記錄（和維護）兩者兼而有之？

Answer 1

好吧，這是我想出的。

我在依賴項屬性上使用了一個特殊的xml標記，它將被一個xsl轉換所取代。沒有它就可以做到，但是Visual Studio會發出警告，因爲該字段看起來沒有記錄。

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

C＃屬性按照慣例記錄，只要確保不要忘記值描述。

/// <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{...} } 

Visual Studio在構建過程中根據這些註釋創建一個xml文件。通過一些xsl轉換，dpdoc節點被屬性文檔的修改版本所取代。生成的xml文件與我們很好地記錄屬性標識符相同。它甚至還包括一張紙條，上面有訪問變量的另一種方式：

/// <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(...) 

這樣一來，既API的有適當的文件，我們也不需要複製的代碼的文檔。 xsl轉換可以在生成後事件中完成，也可以集成到文檔生成過程中。

這裏的XSL：

<?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> 

爲什麼我想有這樣的說法：

• 兩個屬性標識符（在DependencyProperty實例）和屬性，是公開的，因此可以合法地被用來訪問該財產。對於同一個邏輯變量，我們有兩個API。
• 代碼文檔應該描述什麼不是已經存在的。在這種情況下，它應該描述財產的含義及其價值以及如何正確使用它。既然屬性標識符和c＃屬性都引用相同的邏輯變量，則它們具有相同的含義。
• 用戶可以自由選擇兩種方式之一來訪問邏輯變量，而不會意識到另一種。兩者都必須妥善記錄。
• 複製粘貼代碼註釋與複製粘貼代碼一樣糟糕。

Answer 2

你應該記錄和維護兩者。一個是依賴項屬性，另一個是一個常規屬性，恰好實現爲訪問該依賴項屬性。他們不是一回事，需要單獨的文檔。