Как документировать код .NET с помощью XML-комментариев

В любой профессиональной среде правильное документирование кода с комментариями необходимо для долговременного чтения. Для кода .NET Microsoft предоставляет систему комментариев на основе XML, обеспечивающую расширенную поддержку IDE.

Что такое XML-комментарии?

По сути, XML-комментарии представляют собой особый вид комментариев, обозначаемых тройной косой чертой (///) и тегами XML, чтобы придать комментарию некоторую структуру. Например, простой итоговый комментарий будет выглядеть следующим образом:

Дело в том, что когда вы используете этот метод в другом месте своего кода, Visual Studio может просмотреть XML и добавить некоторую информацию непосредственно во всплывающее окно Intellisense. Эта система работает для всех типов и даже может использоваться для документирования возвращаемых значений и отдельных параметров. И когда вы распространяете сборку, вы можете распространять XML-файл вместе с ней, чтобы включить те же функции для всех, кто использует вашу библиотеку классов. Это также позволяет легко использовать генераторы статической документации, такие как DocFX и Sandcastle.

Удивительно, но эта функция в основном только для .NET. Ничто не мешает вам использовать эту практику с другими языками, но это то, что Microsoft хорошо поддерживает для своих языков и редакторов, а другие языки обычно не имеют для этого надлежащей поддержки. Мы бы хотели, чтобы поддержка этого была расширена на другие языки и редакторы, поскольку это довольно универсально полезно.

Его очень просто использовать. Просто трижды нажмите клавишу косой черты (///) над методом, классом или другим типом, и Visual Studio вставит шаблон для ввода. Это избавит вас от хлопот, связанных с его вводом. out вручную, что означает, что на самом деле нет причин не использовать их вместо традиционных комментариев с двойной косой чертой.

Если ваш метод имеет возвращаемый тип или параметры, Visual Studio также создаст для них поля. Вы увидите свои комментарии, когда перейдете к использованию метода:

Стандарт поддерживает множество видов тегов:

•  отображается в Intellisense всякий раз, когда вы используете метод.
•  похоже на сводку, но не отображается в Intellisense (полезно для написания расширенной документации).
•  документирует тип возвращаемого значения.
•  сообщает разработчикам, какие исключения может создавать метод.
•  – это то же самое, что и return, но для свойств класса.
•  показывает пример кода для документации ( используйте это с ).
•   и  создают кликабельные ссылки на другие методы, обычно используемые для документирования перегрузок.
•  позволяет использовать списки для упорядочения элементов.

Вы можете прочитать документацию Microsoft по стандарту комментариев XML для получения дополнительной информации.