Самодокументирование кода в Visual Studio на примере C#

Самодокументирование – механизм описания различных элементов программы (типов, переменных, методов и т.д.) в самом исходном коде [1].

Описание составляется в виде комментария определённой структуры.

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

Visual Studio имеет в своём составе встроенную систему самодокументирования. Рассмотрим её на примере языка программирования C#.

В C# комментарии предназначенные для самодокументирования (комментарии документации) имеют специальное обозначение при помощи символов «///» и форматируются при помощи специальных XML тэгов.

Ниже перечислены XML тэги, рекомендованные Microsoft [2].

XML тэг Назначение
c Текст, который нужно было бы представить как код.
code Позволяет пометить несколько строк как код
example Описание примера кода
exception Служит для указания возможных исключений.
include Позволяет указать ссылку на файл, в котором содержаться комментарии, используя XPath
list Простой список
para Абзац
param Описание параметра метода (для каждого параметра отдельное описание)
paramref Позволяет указать, что слово в комментариях кода, например в блоке <summary> или <remarks>, ссылается на параметр
permission Документирует доступ к члену класса
remarks Описание члена класса
returns Описание значения, которое возвращает метод
see Ссылка на член класса, который может вызываться из текущей среды компиляции.
seealso Текст в разделе «Смотри также»
summary Общее описание
typeparam Объявление универсального типа или метода для описания параметра типа
typeparamref Позволяет указать, что слово в комментариях кода, например в блоке <summary> или <remarks>, ссылается на объявление универсального типа или метода для описания параметра типа
value Описание свойства

 

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

Синтаксис в тэгах exception, include, param, paramref, permission, see, seealso и typeparam проверяется компилятором.

Комментарии документации лучше всего добавлять перед описываемым элементом программы. В этом случае Visual Studio после ввода символов «///» и нажатия клавиши «Enter», как правило, самостоятельно создаёт необходимую XML структуру комментария.Программисту остаётся только заполнить содержимое XML тэгов.

Ниже приведён пример метода, для которого составлен комментарий документации.

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

Самодокументирование в действии

Visual Studio может не только анализировать комментарии документации, но и формировать на их основе файлы XML документации для всей сборки в целом.

Для этого нужно в свойствах проекта, на вкладке сборка установить флажок «XML файл документации».

Путь вывода XML документации

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

XML файл документации для программы приведённой в примере выше имеет следующее содержимое.

Здесь важно отметить, что компилятор на самом деле выполнил очень большую часть работы за программиста. Он создал элемент assembly и добавил элементы member для каждого члена класса. Каждый элемент <member> имеет атрибут name с полным именем члена, снабженным префиксом, который говорит о том, является ли он типом (Т:), полем (F:), свойством (P:) или методом (М:).

На основе подобных файлов документации уже может быть создана полноценная справочная система.

Таким образом, штатный механизм самодокументирования кода в Visual Studio решает весь необходимый спектр задач.

Источники:
  1. Самодокументирование кода в Builder;
  2. Рекомендуемые теги для комментариев документации (Руководство по программированию на C#).

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *