- Хроники. - -
Документация на основе комментариев 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]. Тут больше сказать нечего.
Подход заключается в трансформации XML файла документации с помощью XSLT схем. Это долгий и неуклюжий способ, однако предоставляет полный контроль над процессом конвертации. Так как одна трансформация работает с одним файлом и генерирует один файл, потребуется несколько XSLT файлов для разных нужд. Этот вариант подходит разве что для нестандартных решений.
NDoc3 [4] отличный и просто инструмент генерации документации. К сожалению разработка и поддержка закончилась аж в 2005-ом году, а значит покрывает только .NET 2.0. Программа использует проекты, список сборок и настройки которой сохраняются в файле с расширением «.ndoc3». Остается только открыть файл в GUI и нажать на кнопку — «Build».
Sandcastle [5] был создан Microsoft и согласно описанию используется для генерации кода на MSDN. Сам по себе проект мощный и большой и не работающий, так сказать «из коробки». Хотя последнее время ситуация изменилась, для нормальной работы потребует некоторые дополнения и настройки. И так, загружаем:
Устанавливаем, и для запуска используем следующий 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. Так как генерация, это сравнительно долгий процесс, для настройки лучше создать тестовый проект а потом скормить ему нужные файлы.
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
Click here to print.
Copyright © 2008 Все, что меня окружает. All rights reserved.