stp1_method

такие средства генерируют html файлы (либо chm, pdf и любые другие), собранные по документации исходного кода и содержат структуру «namespace, class, members».

Для документирования кода в Microsoft Visual Studio используется специальный тип комментариев — три слеша («///»). Также доступен и особый синтаксис:

///<summary> - общее описание конкретного модуля

///<param> - параметры, принимаемые методом

///<return> - возвращаемые параметры

<seealso>, <see> - ссылки на другие участки кода/внешние ресурсы

Пример:

///<summary>DoWork is a method in the TestClass class.

///<para>Here's how you could make a second paragraph in a description. <see cref="System.Console.WriteLine(System.String)"/> for information about output statements.</para>

///<seealso cref="TestClass.Main"/>

///</summary>

public static void DoWork(int Int1)

{

}

Doxygen

http://doxygen.org/

Для автоматизированного создания пакетов документации существует масса различных программ (NDoc, Sandcastle и другие). Для языка C# каждая из этих программ умеет читать и распознавать структуру файлов, проектов и сборок, находить участки комментариев и выделять их в отдельны файлы.

Общая структура работы программы Doxygen следующая. Прежде всего, генерируется конфигурационный файл, который указывает путь к сборке, тип документации для генерирования, исключения генерации, глубину вхождения и прочие параметры. Дополнительно можно задать шаблон документации (layout file) — внешний вид результата; или использовать шаблон поумолчанию. Шаблон представляет собой файл формата html со специальными вставками. Далее при запуске Doxygen считывает структуру и документацию по заданному пути и генерирует набор результирующих файлов в одном из следующих форматов: xml — для последующего преобразования собственными приложениями; latex + make — для генерации postscript и PDF файлов; rtf — для работы с Microsoft Word; html, chm — для выкладывания в сеть Internet (интерактивная документация).

Контрольные вопросы.

1.Зачем применяется документирование исходного кода ?

2.Какие виды документации Вам известны ?

3.К какому виду документации можно отнести UML диаграммы ?

4.Какие синтаксические конструкции Вам известны для документирования C# кода ?

5.Каким образом работают автоматические генераторы документации ?