记录依赖属性的最佳方式是什么?
我是否应该将 xml 文档放在该字段上:
/// <summary>Documentation goes here</summary>
public static readonly DependencyProperty NameProperty =
DependencyProperty.Register(...)
或在属性(property)上:
/// <summary>and/or here?</summary>
public string Name{ get{...} set{...} }
还是我真的需要记录(和维护)两者?
最佳答案
好的,这就是我想出的。
我在依赖属性中使用了一个特殊的 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
node 被属性文档的修改版本替换。生成的 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。 关于wpf - 依赖属性的 XML 文档,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/4054041/