XML-Dokumentation für Abhängigkeitseigenschaften

Question

Was ist der beste Weg, um eine Abhängigkeitseigenschaft zu dokumentieren?

Soll ich die XML-Dokumentation auf dem Feld:

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

oder auf dem Grundstück:

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

oder muss ich dokumentieren müssen wirklich (und halten), die beide?

Answer 1

Ok, das ist, was ich mir ausgedacht habe.

Ich verwende ein spezielles XML-Tag bei den Abhängigkeitseigenschaften, die durch eine xsl-Umwandlung ersetzt werden. Es wäre möglich, es ohne es zu tun, aber Visual Studio gibt eine Warnung aus, da das Feld nicht dokumentiert ist.

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

Die C# -Eigenschaft ist wie üblich dokumentiert, stellen Sie jedoch sicher, dass die Wertbeschreibung nicht vergessen wird.

Visual Studio erstellt eine XML-Datei aus diesen Kommentaren während der Erstellung. Mit einer kleinen XSL-Transformation wird der Knoten dpdoc durch eine modifizierte Version der Eigenschaftendokumentation ersetzt. Die resultierende XML-Datei ist die gleiche, als ob wir die Eigenschaftskennung gut dokumentiert hätten. Es enthält auch eine kurze Notiz, dass es eine alternative Möglichkeit, die Variable für den Zugriff auf:

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

Auf diese Weise beide API haben ordnungsgemäße Dokumentation und wir brauchen nicht die Dokumentation im Code zu duplizieren. Die xsl-Transformation kann in den Post-Build-Ereignissen durchgeführt oder in den Dokumentationserstellungsprozess integriert werden.

Hier ist das 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> 

Warum ich will es haben auf diese Weise:

• Sowohl die Eigenschaft Kennung (die DependencyProperty Instanz) und die Eigenschaft, sind öffentlich und können daher legal verwendet werden, um auf das Eigentum zuzugreifen. Tausend haben wir zwei APIs zu derselben logischen Variable.
• Code-Dokumentation sollte beschreiben, was nicht schon da ist zu sehen. In diesem Zusammenhang sollte die Bedeutung der Eigenschaft und ihres Wertes beschrieben und beschrieben werden. Da beide, Property Identifier und die Eigenschaft C#, auf die gleiche logische Variable verweisen, haben sie die gleiche Bedeutung.
• Der Benutzer kann frei eine der beiden Möglichkeiten wählen, auf die logische Variable zuzugreifen, und sich der anderen nicht bewusst sein. Though beide müssen ordnungsgemäß dokumentiert werden.
• Kopieren-Einfügen von Code-Kommentare ist genauso schlimm wie Kopieren-Einfügen-Code.

Answer 2

Sie sollten beide dokumentieren und pflegen. Eine ist die Abhängigkeitseigenschaft, die andere ist eine reguläre Eigenschaft, die zufällig so implementiert wird, dass sie auf diese Abhängigkeitseigenschaft zugreift. Sie sind nicht das Gleiche und erfordern eine separate Dokumentation.