XML documentation for dependency properties

Question

What is the best way to document a dependency property?

Should I put xml documentation in a field:

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

or properties:

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

or do I really need to document (and maintain) both?

Answer 1

Well, that’s what I came up with.

I use a special xml tag in dependency properties that will be replaced by xsl conversion. This could have been done without it, but then Visual Studio displays a warning because the field is displayed undocumented.

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

The C # property is documented as usual, just make sure you don't forget the value description.

 /// <summary>Gets or sets the position of this element</summary> /// <value>Position (in pixel) relative to the parent 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 creates an XML file from these comments during creation. With a little xsl conversion, the dpdoc node is replaced with a modified version of the property documentation. The resulting xml file is the same as if we had a well-documented property identifier. It even includes a short note that there is an alternative way to access a variable:

 /// <summary>Position (in pixel) relative to the parent 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(...) 

Thus, both APIs have proper documentation, and we do not need to duplicate the documentation in the code. The xsl conversion can be performed in post-build events or integrated into the documentation creation process.

Here is 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> 

Why I want to have it this way:

• The property identifier ( DependencyProperty instance) and the property are publicly available and therefore can be legally used to access the property. We have two APIs for the same boolean variable.
• The code documentation should describe what is not yet visible. In this context, it should describe the value of the property and its value and how to use it correctly. Because both property identifiers and C # properties refer to the same boolean, they have the same value.
• The user is free to choose one of two ways to access the logical variable and does not need to know the other. These documents must be properly documented.
• Copying pasted code comments is just as bad as copying code.

Answer 2

You must document and support both. One of them is a dependency property, the other is a regular property, which is simply implemented as access to this dependency property. They are not the same thing require separate documentation.