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

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

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

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

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

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

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

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

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

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

Ты можешь читать Документация Microsoft по стандарту комментариев XML Чтобы получить больше информации.