C#: XML документирование

Документирующие комментарии используют синтаксис XML и позволяют документировать типы и их члены. Документирующий комментарий должен идти непосредственно перед объявлением типа или его члена и начинаться с трех слэшей:

Многострочный комментарий можно добавить двумя способами:

Обратите внимание на две звездочки в начале второго варианта.

Если при компиляции добавить параметр /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> — позволяет оформить контент в виде маркированного или нумерованного списка либо в виде таблицы; полностью выглядит так:

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

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