Visual Studio с DoxyGen для документации, или мы должны использовать что-то еще?

Ответ 1

Стандартный способ документирования кода С# в Visual Studio - комментарии к документации XML. По-моему, это лучший способ использовать код С#, потому что поддержка этого уже интегрирована в Visual Studio (автоматическое завершение тега комментариев, предупреждение о недостающих или неправильно заданных параметрах,...). Чтобы документировать метод, просто введите три слэша (///) перед телом метода, а Visual Studio введет пустой шаблон комментария для заполнения, например:

/// <summary>
/// 
/// </summary>
/// <param name="bar"></param>
private void Foo(int bar)
{
    // ...
}

Вы можете настроить Visual Studio на создание XML файла из всех комментариев, который затем будет передаваться в генератор документации, например Sandcastle, Если вы хотите использовать Doxygen, это не проблема, поскольку он поддерживает разбор XML-комментариев.

Подводя итог: Я бы рекомендовал использовать комментарии XML по специальным комментариям Doxygen для кода С#. Таким образом, у вас есть все варианты. Вы можете создать документацию в стандартном формате Doxygen, с которым ваша организация знакома (потому что Doxygen поддерживает комментарии XML), плюс у вас есть возможность генерировать документацию в формате, известном разработчикам .NET(с Sandcastle и FileBuilder с поддержкой Sandcastle).

А, а также попробуйте GhostDoc...

Ответ 2

Существует несколько вариантов документации:

• Свободный путь Microsoft. Используйте комментарии документации DocXml, а затем Sandcastle или аналогичный инструмент для создания документации в стиле MSDN. Преимущество этого заключается в том, что Visual Studio распознает документацию (синтаксис - раскрашивает комментарии), и документация сразу же подхвачена системой Intellisense (поэтому, если вы наведите указатель мыши на метод, который вы вызываете, всплывающая подсказка отобразит сводка и информация о параметрах, которые вы ввели в комментарии Doc)

• Свободная система Doxygen. Это проще в использовании и более гибкой, но не поддерживаемой Visual Studio, поэтому вы теряете преимущества окраски intellisense и синтаксиса. С другой стороны, Doxygen анализирует формат DocXml, поэтому вы можете получить лучшее из обоих миров, используя формат DocXml с Doxygen для создания внешней справки.

• Коммерческие продукты, такие как DocumentX, которые позволяют редактировать документацию в окне WYSIWYG.

Я бы рекомендовал начать с комментариев DocXml и Doxygen для создания внешней справки, как самого дешевого и простого способа начать работу, и сохранит все лучшие возможности VIsual Studio (intellisense и т.д.).

Я также предлагаю вам посмотреть мою надстройку, Atomineer Pro Documentation, которая позволяет генерировать и обновлять DocXml, Doxygen, Комментарии Qt или JavaDoc намного быстрее и проще в VS - идеальное дополнение к Doxygen и Sandcastle.

Ответ 3

Doxygen может потреблять комментарии С# doc (///) просто отлично. Документируйте свой код как обычно и запустите doxygen, чтобы отсканировать их в автономные html, chm и pdf файлы. Это, безусловно, самый универсальный, простой и неинвазивный подход.

В то время как doxygen не интегрирован в визуальную студию, он поставляется с простой средой IDE и может тривиально записываться как пользовательский внешний инструмент. Лично я включил doxygen в мои скрипты сборки и работает безупречно.

Наконец, doxygen является кросс-платформенным (что является преимуществом, если вам когда-либо понадобится порт для Mono) и значительно быстрее, чем SandCastle (как для установки, так и для запуска).

Это пример вывода doxygen для кода С# в проекте ~ 1Mloc: http://www.opentk.com/files/doc/annotated.html

Ответ 4

.NET-разработчики используются для формата документации, подобной MSDN, используемой в VS-помощи. Предпочтительно непосредственно интегрировать в VS-помощь, поскольку она дает некоторые бонусные функции, такие как помощь F1, фильтры, унифицированный индекс и TOC. Уже упоминалось несколько инструментов. Я бы добавил еще одно коммерческое решение одним нажатием, VSdocman.

Комментарии к XML-документам великолепны, поскольку они автоматически используются также в быстрой информации IntelliSense и Object Browser.

Ответ 5

Visual Studio не имеет интегрированной системы документации.

Если вы хотите оставаться в соответствии с другими языками, вы можете попробовать использовать Doxygen с Doxycomment Addin для Visual Studio.

Для документации С# или .NET существует несколько инструментов, и наиболее часто используемые (насколько мне известно) Sandcastle.

Наконец, вы можете проверить эту запись в блоге, которая предоставляет небольшой Python script, который преобразует некоторые теги С# в Doxygen.