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

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

alt text alt text

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

ОТВЕТЫ

Ответ 1

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

  • С#: ///

  • VB: '''

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

Ответ 2

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

С#

///<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

Ответ 3

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Ответ 4

Прокомментируйте XML, как это

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

Ответ 5

используйте///, чтобы начать каждую строку комментария и оставить комментарий соответствующий xml для чтения метаданных.

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

Хотя я лично считаю, что эти комментарии обычно вводят в заблуждение, если вы не разрабатываете классы, где код не может быть прочитан его потребителями.

Ответ 6

Те, которые называются Комментарии XML. Они были частью Visual Studio с навсегда.

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

Вот пример из одного из моих сообщений.

Надеюсь, что помогает:)

Ответ 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)
{
}

Ответ 8

Определите подобные методы, и вы получите необходимую помощь.

    /// <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;
    }

Снимок экрана с использованием кода

Ответ 10

Все эти другие ответы имеют смысл, но являются неполными. Visual Studio обрабатывает XML-комментарии, но вы должны включить их. Вот как это сделать:

Intellisense будет использовать комментарии XML, которые вы вводите в исходный код, но вы должны включить их с помощью параметров Visual Studio. Перейдите к Tools > Options > Text Editor. Для Visual Basic включите параметр Advanced > Generate XML documentation comments for '''. Для С# включите параметр Advanced > Generate XML documentation comments for ///. Intellisense будет использовать итоговые комментарии при вводе. Они будут доступны из других проектов после составления проекта, на который делается ссылка.

Чтобы создать внешнюю документацию, вам необходимо сгенерировать XML файл через путь Project Settings > Build > XML documentation file:, который управляет параметром компилятора /doc. Вам понадобится внешний инструмент, который возьмет XML файл в качестве входных данных и создаст документацию по вашему выбору выходных форматов.

Имейте в виду, что генерация XML файла может заметно увеличить время компиляции.

Ответ 11

Кроме того, призрачный doc-модуль визуальной студии будет пытаться создавать и заполнять комментарии заголовка от имени вашей функции.

Ответ 12

У Солмида есть правильный ответ. Для получения дополнительной информации вы можете посмотреть Комментарии XML.