Самодокументирование – механизм описания различных элементов программы (типов, переменных, методов и т.д.) в самом исходном коде [1].
Описание составляется в виде комментария определённой структуры.
При необходимости на основе данных описаний можно с помощью специальных инструментов сформировать справочную систему. Также некоторые среды разработки позволяют на их основе создавать всплывающие подсказки, которые содержат текст описания, что заметно упрощает процесс написания программ.
Visual Studio имеет в своём составе встроенную систему самодокументирования. Рассмотрим её на примере языка программирования C#.
rdp что это, читайте в отдельном материале
В C# комментарии предназначенные для самодокументирования (комментарии документации) имеют специальное обозначение при помощи символов «///» и форматируются при помощи специальных XML тэгов.
Ниже перечислены XML тэги, рекомендованные Microsoft [2].
| XML тэг | Назначение |
| c | Текст, который нужно было бы представить как код. |
| code | Позволяет пометить несколько строк как код |
| example | Описание примера кода |
| exception | Служит для указания возможных исключений. |
| include | Позволяет указать ссылку на файл, в котором содержаться комментарии, используя XPath |
| list | Простой список |
| para | Абзац |
| param | Описание параметра метода (для каждого параметра отдельное описание) |
| paramref | Позволяет указать, что слово в комментариях кода, например в блоке
или , ссылается на параметр |
| permission | Документирует доступ к члену класса |
| remarks | Описание члена класса |
| returns | Описание значения, которое возвращает метод |
| see | Ссылка на член класса, который может вызываться из текущей среды компиляции. |
| seealso | Текст в разделе «Смотри также» |
| summary | Общее описание |
| typeparam | Объявление универсального типа или метода для описания параметра типа |
| typeparamref | Позволяет указать, что слово в комментариях кода, например в блоке
или , ссылается на объявление универсального типа или метода для описания параметра типа |
| value | Описание свойства |
Тэги typeparam и typeparamref предназначены специально для документирования, так называемых, обобщений.
Синтаксис в тэгах exception, include, param, paramref, permission, see, seealso и typeparam проверяется компилятором.
Комментарии документации лучше всего добавлять перед описываемым элементом программы. В этом случае Visual Studio после ввода символов «///» и нажатия клавиши «Enter», как правило, самостоятельно создаёт необходимую XML структуру комментария.Программисту остаётся только заполнить содержимое XML тэгов.
Ниже приведён пример метода, для которого составлен комментарий документации.
|
1 |
/// |
/// Тестовый метод ///
|
1 |
/// |
|
1 2 3 4 5 6 |
Исходная строка /// Возвращает исходную строку private string testMethod (string inp) { return inp; } |
При вызове данного метода в редакторе будет отображаться соответствующая всплывающая подсказка.
Visual Studio может не только анализировать комментарии документации, но и формировать на их основе файлы XML документации для всей сборки в целом.
Для этого нужно в свойствах проекта, на вкладке сборка установить флажок «XML файл документации».
По умолчанию для вывода используется та же папка, что и для самой сборки, а имя файла документации совпадает с именем сборки. Но, при желании можно сменить папку и/или задать файлу другое имя.
XML файл документации для программы приведённой в примере выше имеет следующее содержимое.
|
1 |
WindowsFormsApplication1 |
Тестовый метод
|
1 |
|
1 2 |
Исходная строка Возвращает исходную строку |
Обязательная переменная конструктора.
|
1 |
Освободить все используемые ресурсы.
|
1 |
|
1 |
истинно, если управляемый ресурс должен быть удален; иначе ложно. |
Требуемый метод для поддержки конструктора — не изменяйте содержимое этого метода с помощью редактора кода.
|
1 |
Главная точка входа для приложения.
|
1 |
Класс ресурсов со строгим типом для поиска локализованных строк и пр.
|
1 |
Возврат кэшированного экземпляра ResourceManager, используемого этим классом.
|
1 |
Переопределяет свойство CurrentUICulture текущего потока для всех подстановки ресурсов с помощью этого класса ресурсов со строгим типом.
|
1 |
Здесь важно отметить, что компилятор на самом деле выполнил очень большую часть работы за программиста. Он создал элемент assembly и добавил элементы member для каждого члена класса. Каждый элемент имеет атрибут name с полным именем члена, снабженным префиксом, который говорит о том, является ли он типом (Т:), полем (F:), свойством (P:) или методом (М:).
На основе подобных файлов документации уже может быть создана полноценная справочная система.
Таким образом, штатный механизм самодокументирования кода в Visual Studio решает весь необходимый спектр задач.
Добавить комментарий