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

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

• ///
  محدد لسطر واحد. هذا هو النموذج الذي تجده في أمثلة الوثائق والذي يتم استخدامه من قبل قوالب مشروع #Visual C. إذا كان هناك حرف أبيض يتبع المحدد لا يتم تضمين ذلك الحرف في مخرجات XML.

  ملاحظة

  لدى Visual Studio IDE ميزة تسمى "تحرير التعليقات الذكي" الذي يقوم تلقائياً بإدراج علامات <summary> و </summary> ثم بتحريك المؤشر داخل هذه العلامات بعد كتابة المحدد /// في محرر التعليمات البرمجية. ادخل على هذه الميزة من تنسيق أو C# ، محرر نص أو مربع الحوار خيارات في صفحات الخصائص للمشروع الخاص بك.

• /** */
  المحددات متعددة الأسطر.

توجد هناك بعض قواعد التنسيق التي يجب اتباعها عند استخدام المحددات /** */.

• على السطر الذي يتضمن المحدد /** إذا كان باقي السطر مساحة بيضاء لن تتم معالجة السطر كتعليق. إذا كان أول حرف بعد المحدد /** مساحة بيضاء يتم تجاهله ويتم معالجة بقية السطر. وإن لم يكن، فيتم معالجة كامل النص بعد المحدد /** كجزء من التعليق.

• على السطر الذي يتضمن المحدد */ إذا كان هناك مساحة بيضاء فقط حتى المحدد */ يتم تجاهل السطر. وإن لم يكن ذلك، فإن النص الموجود على السطر وصولا إلى المحدد */ يتم معالجته كجزء من التعليق، خاضعاً لقواعد مطابقة النمط الموضحة في التعداد النقطي التالي.

• للأسطر التي تأتي من بعد المحدد /** يبحث المحول البرمجي عن نقوش شائعة في بداية كل سطر. يمكن أن تتألف النقوش من مسافات بيضاء اختيارية ثم على علامة نجمية (*) متبوعاً بمسافات بيضاء اختيارية أكثر. إذا عثر المحول البرمجي على نقش شائع في بداية سطرٍ ما لا يبدأ بالمحدد /** ولا المحدد */ فإنه يتجاهل هذا النقش.

توضح الأمثلة التالية هذه القواعد.

• الجزء الوحيد من التعليقات التالية الذي سيتم معالجته هو السطر الذي يبدأ بـ "<summary>. التنسيقات الثلاثة للعلامات تنتج نفس التعليقات.

  /** <summary>text</summary> */ 
  
  /** 
  <summary>text</summary> 
  */ 
  
  /** 
   * <summary>text</summary> 
  */ 
  

• يتعرف المحول البرمجي على نموذج شائع من "*" في بداية الأسطر الثاني والثالث. لا يتم تضمين النقش في المخرجات.

  /** 
   * <summary> 
   * text </summary>*/ 
  

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

  /** 
   * <summary> 
     text </summary>
  */ 
  

• لا يجد المحول البرمجي على أي نقوش في التعليق التالي لسببين. أولاً، عدد المسافات قبل علامة النجمة (*) غير متناسق. ثانياً، يبدأ السطر الخامس بعلامة تبويب ولا يتطابق مع المسافات. لذلك، تتم معالجة كل النصوص من السطر الثاني حتى السطر الخامس كجزء من التعليق.

  /** 
    * <summary> 
    * text 
   *  text2 
      *  </summary> 
  */ 
  

راجع أيضًا:

المرجع

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

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

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

المبادئ

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