Автоматическое создание документации по функциям в Visual Studio


91

Мне было интересно, есть ли способ (надеюсь, сочетание клавиш) для создания заголовков функций автоматического создания в Visual Studio.

Пример:

Private Function Foo(ByVal param1 As String, ByVal param2 As Integer)

И это автоматически стало бы чем-то вроде этого ...


'---------------------------------- 
'Pre: 
'Post:
'Author: 
'Date: 
'Param1 (String): 
'Param2 (Integer): 
'Summary: 
Private Function Foo(ByVal param1 As String, ByVal param2 As Integer)

1
Если вы попали на эту страницу из-за того, что эта функция в вашей IDE не работает, вам следует убедиться, что ваш код компилируется, и повторите попытку. Эта функция не работает, если в вашем коде есть ошибки синтаксического анализа.
krowe2

Как сгенерировать список дел в xamarin?
Manthan

Ответы:


160

Сделайте "три одиночных комментария-маркера"

В C # это ///

который по умолчанию выплевывает:

/// <summary>
/// 
/// </summary>
/// <returns></returns>

Вот несколько советов по редактированию шаблонов VS.


7
А в VB.NET это тройные одинарные кавычки (как упоминалось в другом ответе)
peSHIr

1
Это довольно мило, я не знал об этом
Брендан

Команда «Создать комментарии документации XML для ///» не будет работать, если предыдущая строка без пробела начинается с «///»
Moon Waxing

Можно ли сделать это автоматически для каждого метода, свойства и переменной? Даже если код уже существует?
Робин

ссылка на подсказки снова исправлена . проклят тебя, односторонняя паутина!
Майкл Паулюконис

48

GhostDoc !

Щелкните функцию правой кнопкой мыши, выберите «Задокументировать» и

private bool FindTheFoo(int numberOfFoos)

становится

/// <summary>
/// Finds the foo.
/// </summary>
/// <param name="numberOfFoos">The number of foos.</param>
/// <returns></returns>
private bool FindTheFoo(int numberOfFoos)

(да, это все автоматически).

Он поддерживает C #, VB.NET и C / C ++. По умолчанию он отображается на Ctrl+ Shift+ D.

Помните: вы должны добавить в документацию информацию помимо сигнатуры метода. Не останавливайтесь только на автоматически созданной документации. Ценность такого инструмента заключается в том, что он автоматически генерирует документацию, которую можно извлечь из сигнатуры метода, поэтому любая добавляемая вами информация должна быть новой .

При этом я лично предпочитаю, когда методы полностью самодокументируются, но иногда у вас будут стандарты кодирования, требующие внешней документации, и тогда такой инструмент, как этот, избавит вас от лишнего умственного набора текста.


16
И это именно та «документация», которую я ненавижу. Он просто добавляет байты, ничего не сообщая мне, о которых мне еще не говорят имена методов и параметров. Не делайте этого, не отредактировав комментарий в какой-нибудь стоящий ... :-(
peSHIr

13
Конечно, вы должны редактировать его, чтобы добавить информацию. Но как шаблон он очень хорош.
Расмус Фабер,

3
@Rasmus: Это шаблон, который для хорошей документации следует полностью выбросить и все равно переписать, поскольку в нем нет информационного содержания. Так что на самом деле это больше усилий, чем если бы он был пустым.
Joey

36
///

- это ярлык для получения блока комментариев "Описание метода". Но убедитесь, что вы написали имя функции и подпись перед ее добавлением. Сначала напишите имя функции и подпись.

Затем над именем функции просто введите ///

и вы получите это автоматически

введите описание изображения здесь


5
милая необычная реплика, твоя анимация.
n611x007 02

1
Как ты это сделал? Мне нравится этот ответ. Никогда раньше такого не видел.
Matthis Kohli

2
мило. одним дополнением будут параметры функции.
amit jha

19

У Visual Assist тоже есть хорошее решение , и его очень легко адаптировать.

После настройки для создания комментариев в стиле doxygen эти два щелчка будут производить -

/**
* Method:    FindTheFoo
* FullName:  FindTheFoo
* Access:    private 
* Qualifier:
* @param    int numberOfFoos
* @return   bool
*/
private bool FindTheFoo(int numberOfFoos)
{

}

(При настройках по умолчанию это немного другое.)


Изменить: способ настройки текста «метод документа» находится в VassistX-> Параметры Visual Assist-> Предложения, выберите «Редактировать фрагменты виртуального интерфейса», Язык: C ++, Тип: Рефакторинг, затем перейдите в «Метод документа» и настройте. Приведенный выше пример создан:

va_doxy


Расскажите, пожалуйста, как вы это устроили в Вирджинии
Дамиан

Подробно изложил ответ. Надеюсь это поможет.
Офек Шилон

Чтобы вставить фрагмент: с курсором в имени / сигнатуре метода, alt + shift + q> «метод документа»
Эндрю

13

Обычно Visual Studio создает его автоматически, если вы добавляете три одиночных маркера комментария над тем, что вы хотите прокомментировать (метод, класс).

В C # это было бы ///.

Если Visual Studio этого не делает, вы можете включить его в

Параметры-> Текстовый редактор-> C # -> Дополнительно

и проверьте

Создание комментариев документации XML для ///

изображенное описание


3

В Visual Basic, если вы сначала создаете свою функцию / подпрограмму, а затем в строке над ней вы набираете три раза, она автоматически сгенерирует соответствующий xml для документации. Это также отображается при наведении курсора мыши в intellisense и при использовании функции.


2

Вы можете использовать фрагменты кода для вставки любых строк.

Кроме того, если вы введете три одинарные кавычки ('' ') в строке над заголовком функции, будет вставлен шаблон заголовка XML, который затем можно будет заполнить.

Эти XML-комментарии могут интерпретироваться программным обеспечением для документирования, и они включаются в выходные данные сборки в виде файла assembly.xml. Если вы сохраните этот XML-файл с DLL и ссылаетесь на эту DLL в другом проекте, эти комментарии станут доступны в intellisense.


Это VB.NET: в C # это ///
peSHIr

0

Я работаю над проектом с открытым исходным кодом под названием Todoc, который анализирует слова для автоматического вывода документации при сохранении файла. Он уважает существующие комментарии и работает очень быстро и плавно.

http://todoc.codeplex.com/

Используя наш сайт, вы подтверждаете, что прочитали и поняли нашу Политику в отношении файлов cookie и Политику конфиденциальности.
Licensed under cc by-sa 3.0 with attribution required.