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

Материал из Википедии — свободной энциклопедии
Перейти к навигации Перейти к поиску

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

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

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

[править | править код]

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

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

Документирующие комментарии, как правило, оформляются как многострочные комментарии в стиле языка Си. В каждом случае комментарий должен находиться перед документируемым элементом. Первым символом в комментарии (и в начале строк комментария) должен быть *. Блоки разделяются пустыми строками.

Пример документирующего комментария на языке PHP:

/**
* Имя или краткое описание объекта
* 
* Развернутое описание
* 
* @имя_дескриптора значение
* @return тип_данных
*/

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

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

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

[править | править код]

Примеры для разных языков и сред программирования:

Примечания

[править | править код]
  1. HappyDoc Source Documentation. Дата обращения: 27 января 2006. Архивировано 27 ноября 2020 года.
  2. PasDoc — pasdoc. Дата обращения: 7 сентября 2009. Архивировано 20 декабря 2016 года.
  3. Perl programming documentation — perldoc.perl.org. Дата обращения: 17 июня 2009. Архивировано 30 января 2009 года.
  4. RDoc — Document Generator for Ruby Source. Дата обращения: 19 июня 2022. Архивировано 6 июня 2022 года.
  5. ROBODoc — automating the software documentation process. Дата обращения: 27 января 2006. Архивировано 13 мая 2011 года.
  6. NDoc Online. Дата обращения: 27 января 2006. Архивировано 3 июля 2006 года.
  7. Doug Hellmann, Writing Technical Documentation with Sphinx, Paver, and Cog Архивная копия от 16 января 2013 на Wayback Machine
  8. http://www.helixoft.com/vbdocman/ (недоступная ссылка)
  9. Knuth and Levy:CWEB Архивировано 20 ноября 2012 года.