Документация на основе комментариев C# кода

Для описания API проекта или библиотеки, а иногда — просто придания ценности проекту и облегчения жизни следующим разработчикам используются комментарии кода. Тут 2 приема «//» комментарий кода «///» комментарий для документации с дополнительными тегами и т.д. Комментарии в тремя косыми конвертируются студией в XML файл документации (если этого не происходит, нужно поставить соответствующий флаг в настройках проекта. Но использовать XML в качестве помощи для разработчика не очень удобно, по этому есть специальный софт — преобразующий этот файл в надлежащий вид.

MSDN Reference и JavaDoc это пример работы подобных генераторов. Таких генераторов огромное количество, но к сожалению некоторые или просто заброшены, или просто не подходят для нормального отображения нужного языка (это может быть даже с теми генераторами, которые официально заявляют о поддержке — пример Doxygen, хотя, кому как нравится). В свое время, я перепробовал множество генераторов, но чтобы сэкономить ваше время, расскажу о том, который использую и сейчас.

Теги документации

Полную и актуальную информацию о тегах проще всего получить с сайта MSDN. Тут больше сказать нечего.

XSLT трансформация

Подход заключается в трансформации XML файла документации с помощью XSLT схем. Это долгий и неуклюжий способ, однако предоставляет полный контроль над процессом конвертации. Так как одна трансформация работает с одним файлом и генерирует один файл, потребуется несколько XSLT файлов для разных нужд. Этот вариант подходит разве что для нестандартных решений.

NDoc3

NDoc3 отличный и просто инструмент генерации документации. К сожалению разработка и поддержка закончилась аж в 2005-ом году, а значит покрывает только .NET 2.0. Программа использует проекты, список сборок и настройки которой сохраняются в файле с расширением «.ndoc3». Остается только открыть файл в GUI и нажать на кнопку — «Build».

Sandcastle

Sandcastle был создан Microsoft и согласно описанию используется для генерации кода на MSDN. Сам по себе проект мощный и большой и не работающий, так сказать «из коробки». Хотя последнее время ситуация изменилась, для нормальной работы потребует некоторые дополнения и настройки. И так, загружаем:

• Sandcastle — основная библиотека для конвертирования.
• Sandcastle Help File Builder — поддержка создания проектов и графический интерфейс.

Устанавливаем, и для запуска используем следующий BAT файл:

set DXROOT="c:\Program Files (x86)\Sandcastle"
set SHFBROOT="c:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder"
set LANGUAGE="%SHFBROOT%\SandcastleBuilderGUI.exe"

Интерфейс более или менее понятен и похож на NDoc. Так как генерация, это сравнительно долгий процесс, для настройки лучше создать тестовый проект а потом скормить ему нужные файлы.

Другие генераторы C# документации

• LiveDocumenter — мне не подходит, так как использует внутренний формат, открываемый их-же прогрпммой.
• ImmDoc.NET — сравнительно новый генератор, подающий большие надежды. Пока работает только с .NET 2.0, насколько он хорош — покажет время.
• Сводная таблица генераторов — известная контрибуторам Wikipedia.

Метки:C#, HTML, Microsoft