- Хроники. - -

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

Posted By Ikutsin On 10 декабря 2010 @ 15:21 In .NET C#,Как? | Comments Disabled

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

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

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

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

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

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

NDoc3

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

Sandcastle

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

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

Устанавливаем, и для запуска используем следующий 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 [8] — мне не подходит, так как использует внутренний формат, открываемый их-же прогрпммой.
  • ImmDoc.NET [9] — сравнительно новый генератор, подающий большие надежды. Пока работает только с .NET 2.0, насколько он хорош — покажет время.
  • Сводная таблица генераторов [10] — известная контрибуторам Wikipedia.

Article printed from Хроники.:

URL to article: /1839-dokumentaciya-na-osnove-kommentariev-c-koda

URLs in this post:

[1] Image: /wp-content/uploads/2010/12/icub_small_new-white.gif

[2] Doxygen: http://www.stack.nl/~dimitri/doxygen/

[3] MSDN: http://msdn.microsoft.com/ru-ru/library/5ast78ax.aspx

[4] NDoc3: http://ndoc.sourceforge.net/

[5] Sandcastle: http://blogs.msdn.com/b/sandcastle/

[6] Sandcastle: http://sandcastle.codeplex.com/

[7] Sandcastle Help File Builder: http://shfb.codeplex.com/

[8] LiveDocumenter: http://theboxsoftware.com/products/live-documenter/

[9] ImmDoc.NET: http://immdocnet.codeplex.com/

[10] Сводная таблица генераторов: http://en.wikipedia.org/wiki/Comparison_of_documentation_generators

Copyright © 2008 Все, что меня окружает. All rights reserved.