Как иметь комментарии в IntelliSense для функции в Visual Studio?

Question

В Visual Studio и C # при использовании встроенной функции, такой как ToString (), IntelliSense показывает желтое поле, объясняющее, что он делает.

Как это можно сделать для функций и свойств, которые я пишу?

Answer 1

Чтобы создать область, в которой вы можете указать описание функции и каждый параметр для функции, введите следующую строку в строке перед вашей функцией и нажмите Введите :

• C #: ///

• VB: '''

См. Рекомендуемые теги для комментариев документации (Руководство по программированию в C #) для получения дополнительной информации о структурированном контенте, который вы можете включить в эти комментарии.

Answer 2

То, что вам нужно, это xml comments - в основном, они следуют этому синтаксису (смутно описанному Solmead):

C #

///<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> - текст, который вы хотели бы указать в виде кода.
Тег <<em> c > позволяет указать, что текст в описании должен быть помечен как код. Используйте <<em> code >, чтобы указать несколько строк в виде кода.

<code>content - текст, который вы хотите пометить как код.
Тег <<em> code > позволяет указать несколько строк в виде кода. Используйте <<em> c >, чтобы указать, что текст в описании должен быть помечен как код.

<example>description</example> - описание примера кода.
Тег <<em> example > позволяет указать пример использования метода или другого члена библиотеки. Обычно это связано с использованием тега <<em> code >.

<exception cref="member">description</exception> - описание исключения.
Тег <<em> exception > позволяет указать, какие исключения могут быть выброшены. Этот тег можно применять к определениям методов, свойств, событий и индексаторов.

<include file='filename' path='tagpath[@name="id"]' />
Тег <<em> include > позволяет вам ссылаться на комментарии в другом файле, которые описывают типы и элементы в вашем исходном коде. Это альтернатива размещению комментариев к документации непосредственно в файле исходного кода. Поместив документацию в отдельный файл, вы можете применять исходный контроль к документации отдельно от исходного кода. Один человек может получить файл исходного кода, а другой - документацию. Тег <<em> include > использует синтаксис XML XPath. Обратитесь к документации XPath, чтобы узнать, как настроить <<em> include >.

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

Блок <<em> listheader > используется для определения строки заголовка таблицы или списка определений. При определении таблицы вам нужно только указать запись для термина в заголовке. Каждый элемент в списке указывается с помощью блока <<em> item >. При создании списка определений вам нужно будет указать и термин, и описание. Однако для таблицы, маркированного списка или нумерованного списка вам нужно только указать запись для описания. Список или таблица могут содержать столько блоков <<em> item >, сколько необходимо.

<para>content</para>
Тег <<em> para > предназначен для использования внутри тега, например <<em> summary >, <<em> remarks > или <<em> возвращает > и позволяет добавить структуру к тексту.

<param name="name">description</param>
Тег <<em> param > должен использоваться в комментарии для объявления метода, чтобы описать один из параметров для метода. Чтобы задокументировать несколько параметров, используйте несколько тегов <<em> param >.
Текст для тега <<em> param > будет отображаться в IntelliSense, обозревателе объектов и в веб-отчете с комментариями кода.

<paramref name="name"/>
Тег <<em> paramref > позволяет указать, что слово в коде комментирует, например, в блоке <<em> summary > или <<em> remarks >. к параметру. XML-файл может быть обработан для форматирования этого слова каким-либо отличным способом, например шрифтом, выделенным жирным или курсивом.

<<code>permission cref="member">description</permission>
Тег <<em> Разрешение > позволяет документировать доступ пользователя. Класс PermissionSet позволяет указать доступ к члену.

<remarks>description</remarks>
Тег <<em> remarks > используется для добавления информации о типе, дополняя информацию, указанную в <<em> summary >. Эта информация отображается в Обозревателе объектов.

<returns>description</returns>
Тег <<em> возвращает > должен использоваться в комментарии для объявления метода для описания возвращаемого значения.

<see cref="member"/>
Тег <<em> see > позволяет указать ссылку из текста. Используйте <<em> seealso >, чтобы указать, что текст должен быть помещен в раздел См. Также. Используйте атрибут cref для создания внутренних гиперссылок на страницы документации для элементов кода.

<seealso cref="member"/>
Тег <<em> seealso > позволяет вам указать текст, который вы хотите отображать в разделе «См. Также». Используйте <<em> см. >, чтобы указать ссылку из текста.

<summary>description</summary>
Тег <<em> summary > должен использоваться для описания типа или члена типа. Используйте <<em> remarks >, чтобы добавить дополнительную информацию в описание типа. Используйте атрибут cref для включения инструментов документации, таких как Sandcastle, для создания внутренних гиперссылок на страницы документации для элементов кода. Текст для тега <<em> summary > является единственным источником информации о типе в IntelliSense, а также отображается в обозревателе объектов.

<typeparam name="name">description</typeparam>
Тег <<em> typeparam > должен использоваться в комментарии для описания обобщенного типа или метода для описания параметра типа. Добавьте тег для каждого параметра типа универсального типа или метода. Текст для тега <<em> typeparam > будет отображаться в IntelliSense, веб-отчете с комментариями кода браузера объектов.

<typeparamref name="name"/>
Используйте этот тег, чтобы разрешить потребителям файла документации форматировать слово каким-либо отличным способом, например курсивом.

<value>property-description</value>
Тег <<em> value > позволяет вам описать значение, которое представляет свойство. Обратите внимание, что при добавлении свойства с помощью мастера кода в среде разработки Visual Studio .NET оно добавляет тег <<em> summary > для нового свойства. Затем вам нужно вручную добавить тег <<em> value > для описания значения, которое представляет свойство.

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 Comments . Они были частью Visual Studio с незапамятных времен.

Вы можете упростить процесс документирования, используя GhostDoc , бесплатную надстройку для Visual Studio, которая генерирует для вас комментарии в формате XML. Просто поместите курсор на метод / свойство, которое хотите задокументировать, и нажмите Ctrl-Shift-D.

Вот пример из одного из моих постов .

Надеюсь, это поможет:)

Answer 7

В CSharp: если вы создадите схему метода / функции с ее пармами, то при добавлении трех прямых косых черт она автоматически сгенерирует раздел сводки и секции.

Итак, я вставил:

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

read http://msdn.microsoft.com/en-us/library/3260k4x7.aspx Простое указание комментариев не покажет справочные комментарии в intellisense.

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

Все остальные ответы имеют смысл, но они неполны. 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 может значительно увеличить время компиляции.