كيف يكون لديك تعليقات في IntelliSense للوظيفة في Visual Studio؟

Question

في Visual Studio وC#، عند استخدام وظيفة مضمنة مثل ToString()، يعرض IntelliSense مربعًا أصفر يشرح ما يفعله.

كيف يمكنني الحصول على ذلك للوظائف والخصائص التي أكتبها؟

Answer 1

لإنشاء منطقة حيث يمكنك تحديد وصف للوظيفة وكل معلمة للوظيفة، اكتب ما يلي في السطر قبل وظيفتك واضغط يدخل:

• ج#: ///

• فب: '''

يرى العلامات الموصى بها لتعليقات التوثيق (دليل برمجة C#) لمزيد من المعلومات حول المحتوى المنظم الذي يمكنك تضمينه في هذه التعليقات.

Answer 2

ما تحتاجه هو تعليقات XML - في الأساس، يتبعون بناء الجملة هذا (كما وصفه سولميد بشكل غامض):

ج#

///<summary>
///This is a description of my function.
///</summary>
string myFunction() {
     return "blah";
}

VB

'''<summary>
'''This is a description of my function.
'''</summary>
Function myFunction() As String
    Return "blah"
End Function

Answer 3

<c>text</c> - النص الذي ترغب في الإشارة إليه كرمز.
<ج> تمنحك العلامة طريقة للإشارة إلى أنه يجب وضع علامة على النص الموجود في الوصف كرمز.استخدم <شفرة> للإشارة إلى أسطر متعددة كرمز.

<code>content</code> - النص الذي تريد وضع علامة عليه كرمز.
<شفرة> تمنحك العلامة طريقة للإشارة إلى أسطر متعددة كرمز.استخدم <ج> للإشارة إلى أنه يجب وضع علامة على النص الموجود في الوصف كرمز.

<example>description</example> - وصف لنموذج التعليمات البرمجية.
<مثال> تتيح لك العلامة تحديد مثال لكيفية استخدام طريقة أو عضو مكتبة آخر.يتضمن هذا عادةً استخدام <شفرة> العلامة.

<exception cref="member">description</exception> - وصف الاستثناء.
<استثناء> تتيح لك العلامة تحديد الاستثناءات التي يمكن طرحها.يمكن تطبيق هذه العلامة على تعريفات الأساليب والخصائص والأحداث والمفهرسات.

<include file='filename' path='tagpath[@name="id"]' />
<يشمل> تتيح لك العلامة الرجوع إلى التعليقات الموجودة في ملف آخر والتي تصف الأنواع والأعضاء في كود المصدر الخاص بك.يعد هذا بديلاً لوضع تعليقات التوثيق مباشرة في ملف التعليمات البرمجية المصدر الخاص بك.من خلال وضع الوثائق في ملف منفصل، يمكنك تطبيق التحكم بالمصادر على الوثائق بشكل منفصل عن التعليمات البرمجية المصدر.يمكن لشخص واحد سحب ملف التعليمات البرمجية المصدر ويمكن لشخص آخر سحب ملف الوثائق.<يشمل> تستخدم العلامة بناء جملة XML XPath.ارجع إلى وثائق XPath للتعرف على طرق تخصيص <يشمل> الاستخدام.

<list type="bullet" | "number" | "table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>term</term>
        <description>description</description>
    </item>
</list>

<com.listheader> يتم استخدام الكتلة لتحديد صف العنوان لجدول أو قائمة تعريفات.عند تحديد جدول، ما عليك سوى توفير إدخال للمصطلح في العنوان.يتم تحديد كل عنصر في القائمة بعلامة <غرض> كتلة.عند إنشاء قائمة تعريفات، ستحتاج إلى تحديد كل من المصطلح والوصف.ومع ذلك، بالنسبة للجدول أو القائمة ذات التعداد النقطي أو القائمة المرقمة، فإنك تحتاج فقط إلى توفير إدخال للوصف.يمكن أن تحتوي القائمة أو الجدول على أكبر عدد ممكن من <غرض> كتل حسب الحاجة.

<para>content</para>
<الفقرة> العلامة مخصصة للاستخدام داخل علامة، مثل <ملخص>, <ملاحظات>، أو <عائدات>، ويتيح لك إضافة هيكل إلى النص.

<param name="name">description</param>
<المعلمة> يجب استخدام العلامة في التعليق لإعلان الطريقة لوصف أحد معلمات الطريقة.لتوثيق معلمات متعددة، استخدم عدة <المعلمة> العلامات.
النص ل<المعلمة> سيتم عرض العلامة في IntelliSense، ومتصفح الكائنات، وفي تقرير الويب للتعليقات البرمجية.

<paramref name="name"/>
<com.paramref> تمنحك العلامة طريقة للإشارة إلى كلمة في تعليقات التعليمات البرمجية، على سبيل المثال في علامة <ملخص> أو <ملاحظات> تشير الكتلة إلى معلمة.يمكن معالجة ملف XML لتنسيق هذه الكلمة بطريقة مميزة، مثل الخط الغامق أو المائل.

<permission cref="member">description</permission>
<إذن> تتيح لك العلامة توثيق وصول العضو.تتيح لك فئة PermissionSet تحديد الوصول إلى العضو.

<remarks>description</remarks>
<ملاحظات> يتم استخدام العلامة لإضافة معلومات حول نوع ما، مكملاً المعلومات المحددة بـ <ملخص>.يتم عرض هذه المعلومات في متصفح الكائنات.

<returns>description</returns>
<عائدات> يجب استخدام العلامة في التعليق لتعريف الطريقة لوصف القيمة المرجعة.

<see cref="member"/>
<يرى> تتيح لك العلامة تحديد رابط من داخل النص.استخدم <أنظر أيضا> للإشارة إلى أنه يجب وضع النص في قسم "انظر أيضًا".استخدم السمة cref لإنشاء ارتباطات تشعبية داخلية لصفحات التوثيق الخاصة بعناصر التعليمات البرمجية.

<seealso cref="member"/>
<أنظر أيضا> تتيح لك العلامة تحديد النص الذي قد ترغب في ظهوره في قسم انظر أيضًا.استخدم <يرى> لتحديد رابط من داخل النص.

<summary>description</summary>
<ملخص> يجب استخدام العلامة لوصف نوع أو عضو نوع.استخدم <ملاحظات> لإضافة معلومات تكميلية إلى وصف النوع.استخدم السمة cref لتمكين أدوات التوثيق مثل Sandcastle لإنشاء ارتباطات تشعبية داخلية لصفحات التوثيق لعناصر التعليمات البرمجية.النص ل<ملخص> العلامة هي المصدر الوحيد للمعلومات حول النوع في IntelliSense، ويتم عرضها أيضًا في Object Browser.

<typeparam name="name">description</typeparam>
<com.typeparam> يجب استخدام العلامة في التعليق لنوع عام أو إعلان طريقة لوصف معلمة النوع.أضف علامة لكل معلمة نوع من النوع أو الطريقة العامة.النص ل<com.typeparam> سيتم عرض العلامة في IntelliSense، وهو تقرير الويب الخاص بالتعليقات البرمجية الخاصة بمتصفح الكائنات.

<typeparamref name="name"/>
استخدم هذه العلامة لتمكين مستهلكي ملف التوثيق من تنسيق الكلمة بطريقة مميزة، على سبيل المثال بالخط المائل.

<value>property-description</value>
<قيمة> تتيح لك العلامة وصف القيمة التي تمثلها الخاصية.لاحظ أنه عند إضافة خاصية عبر معالج التعليمات البرمجية في بيئة تطوير Visual Studio .NET، فإنه سيتم إضافة <ملخص> علامة للخاصية الجديدة.يجب عليك بعد ذلك إضافة <قيمة> علامة لوصف القيمة التي تمثلها الخاصية.

Answer 4

قم بالتعليق باستخدام XML، مثل هذا

/// <summary>
/// This does something that is awesome
/// </summary>
public void doesSomethingAwesome() {}

Answer 5

استخدم /// لبدء كل سطر من التعليق وجعل التعليق يحتوي على XML المناسب لقارئ البيانات الوصفية.

///<summary>
/// this method says hello
///</summary>
public void SayHello();

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

Answer 6

تلك تسمى تعليقات XML.لقد كانوا جزءًا من Visual Studio منذ الأبد.

يمكنك جعل عملية التوثيق الخاصة بك أسهل باستخدام GhostDoc, ، وظيفة إضافية مجانية لبرنامج Visual Studio تقوم بإنشاء تعليقات XML-doc لك.ما عليك سوى وضع علامة الإقحام الخاصة بك على الطريقة/الخاصية التي تريد توثيقها، ثم الضغط على Ctrl-Shift-D.

هنا مثال من واحدة من مشاركاتي.

امل ان يساعد :)

Answer 7

في CSharp، إذا قمت بإنشاء مخطط تفصيلي للطريقة/الوظيفة باستخدام Parms، فعند إضافة الخطوط المائلة الثلاثة للأمام، سيتم إنشاء قسم الملخص وparms تلقائيًا.

لذلك أدخلت:

public string myMethod(string sImput1, int iInput2)
{
}

ثم قمت بوضع الثلاثة /// قبله وأعطاني Visual Studio هذا:

/// <summary>
/// 
/// </summary>
/// <param name="sImput1"></param>
/// <param name="iInput2"></param>
/// <returns></returns>
public string myMethod(string sImput1, int iInput2)
{
}

Answer 8

يقرأ http://msdn.microsoft.com/en-us/library/3260k4x7.aspx لن يؤدي مجرد تحديد التعليقات إلى إظهار تعليقات المساعدة في التحسس الذكي.

Answer 9

حدد طرقًا كهذه وستحصل على المساعدة التي تحتاجها.

    /// <summary>
    /// Adds two numbers and returns the result
    /// </summary>
    /// <param name="first">first number to add</param>
    /// <param name="second">second number to </param>
    /// <returns></returns>
    private int Add(int first, int second)
    {
        return first + second;
    }

لقطة شاشة لاستخدام الكود

Answer 10

سيحاول أيضًا مستند Ghost doc الإضافي في الاستوديو المرئي إنشاء تعليقات الرأس وملؤها من اسم وظيفتك.

Answer 11

كل هذه الإجابات الأخرى منطقية، ولكنها غير كاملة.سيقوم Visual Studio بمعالجة تعليقات XML ولكن عليك تشغيلها.وإليك كيفية القيام بذلك:

سيستخدم Intellisense تعليقات XML التي تدخلها في التعليمات البرمجية المصدر الخاصة بك، ولكن يجب تمكينها من خلال خيارات Visual Studio.اذهب إلى Tools > Options > Text Editor.بالنسبة لـ Visual Basic، قم بتمكين Advanced > Generate XML documentation comments for ''' جلسة.بالنسبة لـ C#، قم بتمكين Advanced > Generate XML documentation comments for /// جلسة.سيستخدم Intellisense التعليقات التلخيصية عند إدخالها.ستكون متاحة من مشاريع أخرى بعد تجميع المشروع المشار إليه.

لنصنع او لنبتكر خارجي الوثائق، تحتاج إلى إنشاء ملف XML من خلال ملف Project Settings > Build > XML documentation file: المسار الذي يتحكم في المترجم /doc خيار.ستحتاج إلى أداة خارجية تأخذ ملف XML كمدخل وتنشئ الوثائق حسب اختيارك لتنسيقات الإخراج.

انتبه إلى أن إنشاء ملف XML قد يؤدي إلى زيادة وقت الترجمة بشكل ملحوظ.

Answer 12

سولميد لديه الإجابة الصحيحة.لمزيد من المعلومات يمكنك إلقاء نظرة على تعليقات XML.