Как получить комментарии в 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";
}

ВБ

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

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

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

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

<paramref name="name"/>
<ссылка на параметрТег > позволяет указать, что слово в комментариях к коду, например, в теге <краткое содержание> или <замечания>блок относится к параметру.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, а также отображается в обозревателе объектов.

<typeparam name="name">description</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.

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

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

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

Answer 7

В CSharp, если вы создаете схему метода/функции с помощью 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 Простое указание комментариев не приведет к отображению справочных комментариев в 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 попытается создать и заполнить комментарии заголовка на основе имени вашей функции.

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-комментарии.