Автоматично генерувати документацію щодо функцій у Visual Studio

Мені було цікаво, чи є спосіб (сподіваюся, комбінація клавіш) створити заголовки функцій автоматичного генерування у 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)

Зробіть "три одиничні маркери коментарів"

У C # це ///

який за замовчуванням випльовує:

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

Ось декілька порад щодо редагування шаблонів VS.

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.

Пам'ятайте: вам слід додати до документації інформацію, яка не підписує метод. Не зупиняйтеся лише на автогенерованій документації. Цінність такого інструменту полягає в тому, що він автоматично генерує документацію, яку можна витягти з підпису методу, тому будь-яка інформація, яку ви додаєте, повинна бути новою інформацією.

Тим не менш, я особисто віддаю перевагу, коли методи повністю самодокументують, але іноді у вас будуть стандарти кодування, які вимагають поза документацією, і тоді такий інструмент заощадить вам багато набору тексту.

///

це ярлик для отримання блоку коментарів опису методу. Але перед додаванням переконайтеся, що ви написали ім’я функції та підпис. Спочатку напишіть назву функції та підпис.

Тоді над назвою функції просто введіть ///

і ви отримаєте його автоматично

Visual Assist також має приємне рішення , і це дуже дорого.

Після налаштування, щоб генерувати коментарі в стилі кисню, ці два кліки дадуть -

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

}

(За налаштуваннями за замовчуванням це дещо інше.)

Редагувати: спосіб налаштування тексту "методу документа" знаходиться у розділі VassistX-> Параметри візуальної допомоги-> Пропозиції, виберіть "Редагувати фрагменти VA", Мова: C ++, Тип: Рефакторинг, потім перейдіть до "Метод документа" та налаштуйте. Наведений приклад генерується:

Зазвичай Visual Studio створює його автоматично, якщо ви додаєте три одиничні маркери коментарів над тим, що ви хочете коментувати (метод, клас).

У C # це буде ///.

Якщо Visual Studio цього не робить, ви можете ввімкнути це в

Параметри-> Текстовий редактор-> C # -> Додатково

і перевірити

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

У Visual Basic, якщо ви спочатку створили свою функцію / підпрограму, а потім у рядку над нею ви введете 'тричі, вона автоматично згенерує відповідний xml для документації. Це також з'являється, коли ви наводите курсор миші в intellisense і коли ви використовуєте функцію.

Ви можете використовувати фрагменти коду, щоб вставити будь-які потрібні рядки.

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

Ці коментарі XML можуть бути інтерпретовані програмним забезпеченням для документації, і вони включені у вихідні дані збірки як файл Assembly.xml. Якщо ви зберігаєте цей файл XML із DLL і посилаєтесь на нього в іншому проекті, ці коментарі стають доступними в intellisense.

Я працюю над проектом із відкритим кодом під назвою Todoc, який аналізує слова для автоматичного виведення належної документації при збереженні файлу. Він поважає наявні коментарі і є дуже швидким та плавним.

http://todoc.codeplex.com/