كيفية القيام بما يلي: استخدام ميزات وثائق XML (دليل البرمجة لـ #C)

يوفر النموذج التالي نظرة عامة أساسية حول نوع تم توثيقه.

مثال

// compile with: /doc:DocFileName.xml 

/// <summary>
/// Class level summary documentation goes here.</summary>
/// <remarks>
/// Longer comments can be associated with a type or member 
/// through the remarks tag</remarks>
public class TestClass
{
    /// <summary>
    /// Store for the name property</summary>
    private string _name = null;

    /// <summary>
    /// The class constructor. </summary>
    public TestClass()
    {
        // TODO: Add Constructor Logic here
    }

    /// <summary>
    /// Name property </summary>
    /// <value>
    /// A value tag is used to describe the property value</value>
    public string Name
    {
        get
        {
            if (_name == null)
            {
                throw new System.Exception("Name is null");
            }
            return _name;
        }
    }

    /// <summary>
    /// Description for SomeMethod.</summary>
    /// <param name="s"> Parameter description for s goes here</param>
    /// <seealso cref="System.String">
    /// You can use the cref attribute on any tag to reference a type or member 
    /// and the compiler will check that the reference exists. </seealso>
    public void SomeMethod(string s)
    {
    }

    /// <summary>
    /// Some other method. </summary>
    /// <returns>
    /// Return results are described through the returns tag.</returns>
    /// <seealso cref="SomeMethod(string)">
    /// Notice the use of the cref attribute to reference a specific method </seealso>
    public int SomeOtherMethod()
    {
        return 0;
    }

    /// <summary>
    /// The entry point for the application.
    /// </summary>
    /// <param name="args"> A list of command line arguments</param>
    static int Main(System.String[] args)
    {
        // TODO: Add code to start application here
        return 0;
    }
}

// This .xml file was generated with the previous code sample. <?xml version="1.0"?> <doc>     <assembly>         <name>xmlsample</name>     </assembly>     <members>         <member name="T:SomeClass">             <summary>             Class level summary documentation goes here.</summary>             <remarks>             Longer comments can be associated with a type or member              through the remarks tag</remarks>         </member>         <member name="F:SomeClass.m_Name">             <summary>             Store for the name property</summary>         </member>         <member name="M:SomeClass.#ctor">             <summary>The class constructor.</summary>          </member>         <member name="M:SomeClass.SomeMethod(System.String)">             <summary>             Description for SomeMethod.</summary>             <param name="s"> Parameter description for s goes here</param>             <seealso cref="T:System.String">             You can use the cref attribute on any tag to reference a type or member              and the compiler will check that the reference exists. </seealso>         </member>         <member name="M:SomeClass.SomeOtherMethod">             <summary>             Some other method. </summary>             <returns>             Return results are described through the returns tag.</returns>             <seealso cref="M:SomeClass.SomeMethod(System.String)">             Notice the use of the cref attribute to reference a specific method </seealso>         </member>         <member name="M:SomeClass.Main(System.String[])">             <summary>             The entry point for the application.             </summary>             <param name="args"> A list of command line arguments</param>         </member>         <member name="P:SomeClass.Name">             <summary>             Name property </summary>             <value>             A value tag is used to describe the property value</value>         </member>     </members> </doc> 

التحويل البرمجي للتعليمات البرمجية

أكتب خط الأوامر التالي للتحويل البرمجي للمثال:

csc XMLsample.cs /doc:XMLsample.xml

سيعمل ذلك على إنشاء ملف من نمط XML اسمه XMLsample.xml والذي يمكنك عرضه في المستعرض باستخدام الأمر TYPE.

برمجة نشطة

تبدأ وثائق XML بـ ///. عندما تقوم بإنشاء مشروع جديد تقوم المعالجات بوضع بعض من الأسطر البدائية /// بالنيابة عنك. هناك بعض القيود لمعالجة هذه التعليقات:

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

• يمكن للمطورين من إنشاء علاماتهم الخاصة. توجد مجموعة من العلامات الموصى بها (راجع قسم قراءة المزيد). لدى بعض العلامات الموصى بها معاني خاصة:

  • يتم استخدام علامة <param> لوصف المعلمات. إذا تم استخدامها، سيقوم المحول البرمجي من التحقق من وجود المعلمة ومن أن كل المعلمات تم وصفها في الوثائق. يقوم المحول البرمجي بإصدار رسالة تحذير إذا فشل التحقق.

  • سمة cref يمكن إرفاقها بأي علامة لتوفير مرجع إلى عنصر التعليمات البرمجية. سيقوم المحول البرمجي من التحقق من وجود عنصر التعليمات البرمجية. يقوم المحول البرمجي بإصدار رسالة تحذير إذا فشل التحقق. يتقيد المحول البرمجي بعبارات الـ using عندما يقوم بالبحث عن نوع تم وصفه في سمة cref.

  • يتم استخدام العلامة <summary> من قبل IntelliSense في ‏‫Visual Studio لعرض معلومات إضافية حول نوع أو عضو.

    ملاحظة

    لا يوفر ملف الـ XML معلومات كاملة حول النوع والأعضاء (على سبيل المثال، لا يحتوي على أية معلومات عن النوع). للحصول على معلومات كاملة حول نوع أو عضو, يجب استخدام ملف الوثائق مع انعكاس على النوع الفعلي أو العضو الفعلي.

راجع أيضًا:

المرجع

/doc (خيارات المحول البرمجي# C)

XML تعليقات الوثائق (دليل البرمجة C#)

المبادئ

دليل البرمجة لـ #C