Краткий справочник по составлению документирующих комментариев
В языке C# предусмотрено три вида комментариев. К двум первым относятся комментарии // и /* */, а третий основан на дескрипторах языка XML и называется документирующим комментарием. (Иногда его еще называют XML-комментарием.) Однострочный документирующий комментарий начинается с символов ///, а многострочный начинается с символов /** и оканчивается символами */. Строки после символов /** могут начинаться с одного символа *, хотя это и не обязательно. Если все последующие строки многострочного комментария начинаются с символа *, то этот символ игнорируется.
Документирующие комментарии вводятся перед объявлением таких элементов языка С#, как классы, пространства имен, методы, свойства и события. С помощью документирующих комментариев можно вводить в исходный текст программы сведения о самой программе. При компиляции программы документирующие комментарии к ней могут быть помещены в отдельный XML-файл. Кроме того, документирующие комментарии можно использовать в средстве IntelliSense интегрированной среды разработки Visual Studio.
Дескрипторы XML-комментариев
В С# поддерживаются дескрипторы документации в формате XML, сведенные в табл. 1. Большинство дескрипторов XML-комментариев не требует особых пояснений и действуют подобно всем остальным дескрипторам XML, знакомым многим программистам. Тем не менее дескриптор <list> — сложнее других. Он состоит из двух частей: заголовка и элементов списка. Ниже приведена общая форма дескриптора
|
|
|
<list>:
<listheader>
<term> имя </term>
<description> текст </description>
</listheader>
где текст описывает имя. Для описания таблиц текст не используется. Ниже приведена общая форма элемента списка:
<item>
<term> имя_элемента </term>
<description> текст </description>
</item>
где текст описывает имя_элемента. Для описания маркированных и нумерованных списков, а также таблиц имя элемента не используется. Допускается применение нескольких элементов списка <item>.
Таблица 1. Дескрипторы XML-комментариев
Дескриптор - Описание
<с> код </с> - Определяет текст, на который указывает код, как программный код
<code> код </code> - Определяет несколько строк текста, на который указывает код, как программный код
<example> пояснение </example> - Определяет текст, на который указывает пояснение, как описание примера кода
<exception cref = "имя"> пояснение </exception> - Описывает исключительную ситуацию, на которую указывает имя
<include file = 'fname' path = 'path[0tagName = "tagID " ] ' /> - Определяет файл, содержащий XML-комментарии для текущего исходного файла. При этом fname обозначает имя файла; path — путь к файлу; tagName — имя дескриптора; tagID — идентификатор дескриптора
|
|
|
<list type = "тип""> заголовок списка элементы списка </list> - Определяет список. При.этом тип обозначает тип списка, который может быть маркированным, нумерованным или таблицей
<рага> текст </para> - Определяет абзац текста в другом дескрипторе
<param name = 'имя параметра'> пояснение </param> - Документирует параметр, на который указывает имя параметра. Текст, обозначаемый как пояснение, описывает параметр
<paramref name = "имя параметра" /> - Обозначает имя параметра как имя конкретного параметра
<permission cref = "идентификатор"> пояснение </permission> - Описывает параметр разрешения, связанный с
членами класса, на которые указывает идентификатор. Текст, обозначаемый как пояснение, описывает параметры разрешения
<remarks> пояснение </remarks> - Текст, обозначаемый как пояснение, представляет собой общие комментарии, которые часто используются для описания класса или структуры
<returns> пояснение </returns> - Текст, обозначаемый как пояснение, описывает значение, возвращаемое методом
<see cref = "идентификатор" /> - Объявляет ссылку на другой элемент, обозначаемый как идентификатор
|
|
|
<seealso cref = "идентификатор" /> - Объявляет ссылку типа “см. также" на идентификатор
<summary> пояснение </summary> - Текст, обозначаемый как пояснение, представляет собой общие комментарии, которые часто используются для описания метода или другого члена класса
<typeparam name = "имя параметра"> пояснение </typeparam> - Документирует параметр типа, на который указывает имя параметра. Текст, обозначаемый как пояснение, описывает параметр типа
<typeparamref name = "имя параметра" /> - Обозначает имя параметра как имя параметра типа
Дата добавления: 2019-02-12; просмотров: 229; Мы поможем в написании вашей работы! |
Мы поможем в написании ваших работ!