Комментарии XML - Как (или где) вы создаете комментарии XML для своих пространств имен и библиотеки?

Question

Я понимаю, что если вы /// над классом, полем, методом или свойством Visual Studio начнете создавать для вас комментарии в стиле XML.

Однако, куда я могу пойти, чтобы добавить комментарии XML длямои пространства имен и / или библиотека ...

Например:

• .NET Framework Библиотека классов
  • System.CollectionsПространства имен
    1. Пространство имен System.Collections
    2. Пространство имен System.Collections.Concurrent
    3. ...

Я не уверен, были ли эти страницы созданы вручную или были автоматически созданы с помощью комментариев в стиле XML, добавляемых в соответствующие места?

Answer 1

Это зависит от инструмента, который вы используете для создания документации. С NDoc, я полагаю, вам просто нужно было создать класс с именем NamespaceDoc внутри пространства имен, которое вы хотите документировать. Затем будет использован XML-комментарий этого класса.

Поскольку вопрос помечен как "sandcastle", я предполагаю, что вы действительно используете его. Если это так, этот SO-ответ должен дать подробности.

Обновление: ОК, я просто ( в том же потоке ) увидел, что, очевидно, Sandcastle также понимает классы NamespaceDoc. Кто-то может захотеть закрыть этот вопрос как дубликат.

Answer 2

Чтобы сгенерировать XML-файл, вам нужно включить его в свойствах вашего проекта.Это флажок XML documentation file на вкладке Build свойств проекта.

Если вы включили его и перекомпилировали сборку, рядом со сборкой появится файл XML с тем же именем, что и у этой сборки.Assembly.

Затем вы можете использовать такой инструмент, как sandcastle, чтобы создать файл справки для вашего кода.Sandcastle - это набор инструментов, которые вы можете использовать для настройки всего процесса создания файлов справки.Этот путь потребует много чтения справочного файла и учебных пособий по sandcastle.

В папке примеров установки sandcastle также есть инструмент, который позволяет быстро сгенерировать файл справки, но предлагает меньше возможностей для настройки.

В прошлом я некоторое время использовал плагин для Visual Studio под названием «DocProject».Я не уверен, что он все еще активен, но вы можете найти его в codeplex, если вам интересно: http://docproject.codeplex.com/

Согласно Microsoft, примеры MSDN, на которые вы ссылаетесь, не создаются путем извлечения тегов /// из ихисточник, но это было больше связано с разделением отделов программистов и документаторов, чем с чем-либо еще.