Генератор документации

Генератор документации — программа или пакет программ, позволяющая получать документацию, предназначенную для программистов (документация на API) и/или для конечных пользователей системы, по особым образом комментированному исходному коду и, в некоторых случаях, по исполняемым модулям (полученным на выходе компилятора).

Обычно, генератор анализирует исходный код программы, выделяя синтаксические конструкции, соответствующие значимым объектам программы (типам, классам и их членам/свойствам/методам, процедурам/функциям и т. п.). В ходе анализа также используется мета-информация об объектах программы, представленная в виде документирующих комментариев. На основе всех собранной информации формируется готовая документация, как правило, в одном из общепринятых форматов — HTML, HTMLHelp, PDF, RTF и других.

Документирующие комментарии

Документирующий комментарий — это особым образом оформленный комментарий к объекту программы, предназначенный для использования каким-либо конкретным генератором документации. От того, какой генератор документации применяется, зависит синтаксис конструкций, используемых в документирующих комментариях.

В документирующих комментариях может содержаться информация об авторе кода, описываться назначение объекта программы, смысл входных и выходных параметров — для функции/процедуры, примеры использования, возможные исключительные ситуации, особенности реализации.

Пример документирующего комментария к функции в программе на Java, предназначенного для использования Javadoc:

/**
 * Проверяет, допустимый ли ход.
 * Например, чтобы задать ход e2-e4, напишите isValidMove(5,2,5,4);
 * @author John Doe
 * @param theFromFile Вертикаль, на котором находится фигура
 * @param theFromRank Горизонталь, на которой находится фигура
 * @param theToFile   Вертикаль клетки, на которую выполняется ход
 * @param theToRank   Горизонталь клетки, на которую выполняется ход
 * @return true, если ход допустим, и false, если недопустим
 */
 boolean isValidMove(int theFromFile, int theFromRank, int theToFile, int theToRank)
 {
     …
 }

Популярные генераторы документации

Наиболее известные генераторы документации:

  • Javadoc [1] — для программ на Java
  • Doxygen [2]
  • NDoc [3] и Sandcastle [4] — для программ на C#, VB.NET и других языков платформы .NET
  • Doc-O-Matic [5]
  • Document! X
  • HappyDoc [6]
  • PHPDoc [7] — адаптация Javadoc для использования с PHP
  • POD
  • ROBODoc [8]
  • TwinText
  • VBdocman [9] — для VB6 и VB.NET
  • WEB / CWEB [10]
 
Начальная страница  » 
А Б В Г Д Е Ж З И Й К Л М Н О П Р С Т У Ф Х Ц Ч Ш Щ Ы Э Ю Я
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
0 1 2 3 4 5 6 7 8 9 Home