وثائق 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(...)

وبهذه الطريقة ، يتمتع كل من واجهة برمجة التطبيقات بتوثيق مناسب ولا نحتاج إلى تكرار الوثائق في الكود. يمكن إجراء تحويل 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 مثيل) والممتلكات ، عامة وبالتالي يمكن استخدامها قانونًا للوصول إلى العقار. Thous لدينا اثنين من واجهات برمجة التطبيقات لنفس المتغير المنطقي.
• يجب أن تصف وثائق الكود ما لم يكن موجودًا بالفعل. في هذا السياق ، يجب أن تصف معنى الخاصية وقيمتها وكيفية استخدامها بشكل صحيح. منذ كلاهما ، معرف الخصائص وخاصية C# ، يشير إلى نفس المتغير المنطقي ، ولديهما نفس المعنى.
• يمكن للمستخدم اختيار إحدى الطريقين للوصول إلى المتغير المنطقي ، ولا يكون Mus على دراية بالآخر. يجب توثيق كلاهما بشكل صحيح.
• تعليقات رمز النسخ السيئة بنفس القدر مثل رمز التخلص من النسخ.

Answer 2

يجب عليك توثيق والحفاظ على كليهما. أحدهما هو خاصية التبعية ، والآخر هو خاصية منتظمة تحدث فقط لتنفيذها على أنها تصل إلى خاصية التبعية. فهي ليست نفس الشيء وتتطلب وثائق منفصلة.