Документирующие комментарии используют синтаксис XML и позволяют документировать типы и их члены. Документирующий комментарий должен идти непосредственно перед объявлением типа или его члена и начинаться с трех слэшей:
1 2 | /// <summary>Cancels a running query.</summary> public void Cancel() { ... } |
Многострочный комментарий можно добавить двумя способами:
1 2 3 4 5 6 7 8 | /// <summary> /// Cancels a running query /// </summary> public void Cancel() { ... } /** <summary> Cancels a running query. </summary> */ public void Cancel() { ... } |
Обратите внимание на две звездочки в начале второго варианта.
Если при компиляции добавить параметр /doc, то компилятор будет извлекать документирующие комментарии и сохранит их в отдельный xml файл. Это может быть полезно по двум причинам. Во-первых, если разместить эти файлы в той же директории что и скомпилированная сборка, Visual Studio сможет прочитать эти файлы и использовать их для выдачи подсказок и завершения кода. Во-вторых, с помощью сторонних средств можно преобразовать эти xml файлы в HTML документацию.
Стандартные XML тэги
<summary>...</summary>— позволяет задать текст всплывающих подсказок в Visual Studio<remarks>...</remarks>— дополнительный текст, описывающий тип или его член, используется генераторами документации<param name="name">...</param>— объясняет параметр метода<returns>...</returns>— объясняет возвращаемое методом значение<exception [cref="type"]>...</exception>— список исключений, которые могут быть выброшены методом,crefуказывает тип исключения<permission [cref="type"]>...</permission>— указываетIPermissionтип, требуемый документируемым типом или членом<example>...</example>— позволяет указать пример использования; обычно содержит текст описания и исходный текст (внутри тэгов<c>или<code>)<c>...</c>— обозначает однострочный фрагмент кода; обычно используется внутри тэга<example><code>...</code>— обозначает многострочный фрагмент кода; обычно используется внутри тэга<example><see cref="member">...</see>— вставляет строчную ссылку на другой тип или член; генераторы документации обычно преобразовывают этот тэг в гиперссылку; компилятор выдаст ошибку если ссылаемый тип или член отсутствуют<seealso cref="member">...</seealso>— дополнительная ссылка на другой тип или член; генераторы документации обычно вставляют эту ссылку в секцию «See Also» в конце страницы<paramref name="name"/>— ссылка на параметр из тэгов<summary>или<remarks><para>...</para>— оформляет контент в виде отдельного абзаца<include file='filename' path='tagpath[@name="id"]'>...</include>— добавляет внешний xml файл с документацией; атрибутpathдолжен содержать XPath выражение, ссылающееся на конкретный элемент в файле<list>— позволяет оформить контент в виде маркированного или нумерованного списка либо в виде таблицы; полностью выглядит так:12345678910<list type=[ bullet | number | table ]><listheader><term>...</term><description>...</description></listheader><item><term>...</term><description>...</description></item></list>