Комментарии XML-кода в .NET

Question

Сколько вы используете XML-комментарии в ваших файлах кода и как вы их используете? Я видел, что вы можете использовать их для создания документации XML, но можно ли использовать эту документацию XML для создания файла справки HTML или файла схемы для вашего кода?

Кроме того, использовали ли вы какие-либо инструменты автоматического создания комментариев (например, GhostDoc), и каковы ваши впечатления?

Мысли

Answer 1

XML-документация сама по себе может быть полезна, если вы распространяете XML-файлы из сборки вместе с DLL-библиотеками. Таким образом, любые потребители API получают полезную информацию из среды IDE (через Intellisense или браузер объектов).

Теперь, пожалуй, наибольшее использование XML-комментариев - это создание справочной документации из этих встроенных XML-файлов. Microsoft Sandcastle - это способ решить эту проблему в данный момент. Он может создавать файлы справки HTML 1 (то есть CHM) или справку HTML 2 (то есть файлы справки, которые можно интегрировать в справку Visual Studio). (Примечание: в прошлом вариант NDoc мог показаться более привлекательным - и некоторые люди все еще используют его - но Sandcastle кажется официальным и рекомендуемым методом на данный момент, особенно учитывая, что он достаточно стабилен и достаточно полон для почти цель.) Для начала посетите веб-сайт SandcastleDocs (я полагаю, что он был неофициально собран одним из разработчиков в Microsoft). В частности, вы захотите ознакомиться с графическим интерфейсом файла справки Sandcastle . По моему опыту, он оказался отличным инструментом.

Answer 2

Я пытаюсь сделать это для любого метода, который не является очевидным в отношении того, что он делает. Мне нравится, что он включает документацию в Intellisense.

Answer 3

Да, я использую эту функцию и думаю, что всем разработчикам рекомендуется комментировать свои API. Как только вы сделаете это за несколько apis, и пока вы остаетесь на вершине, поддерживать его действительно не сложно.

Вариант 1: SandCastle Я попытался использовать это, но я обнаружил, что было слишком много инсталляторов, которые мне нужно было запустить, установить и научиться настраивать. В конце концов, я получил файл CHM, но на самом деле мне хотелось чего-то более легкого.

Плюс в том, что конечный продукт выглядит очень профессионально. Это не сработало для моей ситуации.

Вариант 2: NDoc В прошлый раз, когда я проверял, этот проект не поддерживался и работал только с версией 1.1 .NET.

Вариант 3: XSLT Кто-то в CodeProject написал файл xslt для этого

http://www.codeproject.com/KB/XML/XMLDocStylesheet.aspx

Я пробовал это, и вот как это работает. Создайте свой проект и поместите файл xslt в тот же каталог, что и выведенный xml-файл. Если дважды щелкнуть файл XML, вместо документа XML отобразится отформатированная веб-страница.

Для меня это был лучший вариант.

Answer 4

В прошлом я использовал инструмент SandCastle от Microsoft, чтобы сгенерировать документацию в стиле MSDN из комментариев Xml, и мне очень повезло. Предположительно, это инструмент, используемый для генерации всех документов .net Framework, которые также происходят из комментариев XML.

http://msdn.microsoft.com/en-us/vstudio/bb608422.aspx

Answer 5

Как минимум, я включаю комментарии для общедоступного API и генерирую XML-файл. Этого достаточно, чтобы заставить работать intellisense, и это также отображается в Reflector.

Лично я не беспокоюсь по поводу замков из песка и т. Д., Но я мог бы заниматься проектами независимых разработчиков.

Answer 6

Да! Я использую их, и ВСЕ проекты требуют, чтобы я делал то, что мы их включили. Что касается уровня детализации, это зависит от цели кода. Как минимум все параметры и общедоступные методы будут иметь сводную информацию. Сложные элементы обычно имеют примеры кода, и все специально сгенерированные исключения документируются.

Сейчас я использую SandCastle для создания документации, и вы можете перейти на HTML или CHM без каких-либо проблем! Я также использовал SlickEdit, который выполняет синтаксический анализ на лету, и он также отлично работал!

Answer 7

Я использую NuDoc для создания статических сайтов API в формате уценки. API чистый, современный и очень легкий и простой в использовании (если можно так сказать сам;)): http://kzu.to/nudoc

Это также открытый исходный код, поэтому исправления и улучшения всегда приветствуются.

Answer 8

Мы документируем все методы и свойства с помощью комментариев XML. Как для внутренней документации, так и для предоставления файлов справки для наших двоичных файлов. Особенно приятно иметь всплывающую документацию о методе в intellisense.

Мы используем GhostDoc - он может предоставить документацию по умолчанию - часто ОК, но имейте в виду, что GhostDoc может документировать только то, что он может вывести из имен методов и параметров. Поэтому наше правило заключается в том, что вы можете использовать GhostDoc для запуска документации; затем отредактируйте его соответствующим образом - во многих случаях документация по умолчанию для параметров будет просто отличной. В простых случаях мы просто придерживаемся документации по умолчанию, если это имеет смысл.

Файлы справки можно создать с помощью Sandcastle (скачать) . Кроме того, Конструктор файлов справки Sandcastle - это графический интерфейс, который может облегчить вам начало работы с Sandcastle.