День 1205. #ЗаметкиНаПолях
Профессиональное Документирование Кода
Все мы (надеюсь) документируем свои классы и методы с помощью XML комментариев <summary>, которые можно добавить с помощью тройного слеша (///) над заголовком метода/класса. Однако далеко не все используют все возможности этой документации, редко выходя за описание собственно элемента, параметров в <param> и возврата в <returns>. Вот некоторые полезные теги, позволяющие сделать подсказки более информативными.
1. Секция <remarks>
Добавит новый абзац текста после текста описания в summary, в котором можно указать дополнительную информацию. Кстати, можно добавить только один блок <remarks>, остальные просто игнорируются. Однако можно разделить текст внутри <remarks> на параграфы с помощью тега <para>.
2. Секция <exception>
Позволяет описать исключения, которые может выбросить метод:
<exception cref="класс">описание</exception>
Класс исключения должен быть доступен из текущего кода при компиляции.
3. Тег <inheritdoc/>
Позволяет унаследовать описание из другого элемента (класса, интерфейса или метода).
- <inheritdoc/> для класса наследует все описания всех членов.
- <inheritdoc cref="сигнатура"/> - позволяет указать, из какого члена унаследовать описание. Существующие теги на текущем члене не будут перезаписаны.
- <inheritdoc [cref=""] path="путь"/> - позволяет указать путь XPath к тегам, которые нужно унаследовать. Таким образом можно отфильтровывать ненужные или только нужные теги.
4. Тег <paramref/>
Позволяет в описании сослаться на параметр метода, выделив его в тексте: <paramref name="параметр"/>.
5. Тег <see/>
Позволяет добавить ссылку на другой объект или внешний источник в тексте.
- <see cref="сигнатура"/> - ссылка на член или поле, доступное для вызова из текущей среды компиляции.
- <see href="ссылка" /> - кликабельная ссылка на указанный URL. Например, <see href="https://github.com">GitHub</see> создаёт кликабельную ссылку с текстом GitHub, которая ссылается на https://github.com.
- <see langword="слово" /> - ключевое слово языка, например true или одно из других допустимых ключевых слов. Кроме того, правильно отображает ключевое слово в подсказке (например, true в C# и True в VB).
6. Тег <seealso/>
Аналогично тегу <see/> позволяет добавлять кликабельные ссылки на другой объект или внешний источник в секции «См. также». Нельзя использовать внутри <summary>.
7. Тег <include/>
Позволяет ссылаться на комментарии в отдельном файле, описывающие типы и элементы в исходном коде:
<include file='путь к файлу' path='путь к элементу' />
Использование внешнего файла является альтернативой размещению документации непосредственно в файле исходного кода. Это позволяет применять систему управления версиями к документации отдельно от исходного кода. Один человек может менять файл исходного кода, а другой — файл документации.
Источник: docs.microsoft.com/en-us/d…ded-tags
