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


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

Генератор документации — программа или пакет программ, позволяющая получать документацию, предназначенную для программистов (документация на 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)
  {
      . . .
  }

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

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

См. также

Примечания


Wikimedia Foundation. 2010.

Смотреть что такое "Генератор документации" в других словарях:

  • Генератор — (от лат. generator  производитель)  устройство, аппарат или машина: производящие какие либо продукты (генератор ацетиленовый, лёдогенератор, парогенератор, газогенератор, генератор водорода) вырабатывающие электрическую энергию… …   Википедия

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

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

  • XHelpGen — Генератор документации, изначально придуманный Владимиром Кладовым для библиотеки XCL, а затем адаптированный для KOL  кодоэкономичной библиотеки. Генерация выполняется автоматически на основе комментариев к исходному коду (на языке Delphi… …   Википедия

  • Javadoc — Тип Генератор документации Разработчик Sun Microsystems Операционная система кроссплатформенная Последняя версия 1.50 Лицензия GNU GPL 2 + «Classpath exception»[1] …   Википедия

  • VSdocman — Тип генератор документации Разработчик Helixoft Операционная система Windows Языки интерфейса английский Последняя версия 4.4 (8 октября 2009) Лицензия …   Википедия

  • JSDoc — JSDoc  генератор документации в HTML формате из комментариев исходного кода на JavaScript. Синтаксис JSDoc похож на синтаксис Javadoc, который используется для документирования Java кода, но предназначен для работы с языком JavaScript,… …   Википедия

  • Epydoc — Тип Генератор документации Разработчик Эдуард Лопер и др. Операционная система Любая, где работает Python Последняя версия 3.0.1 (30 января 2008) Лицензия Лицензия MIT Сайт …   Википедия

  • Sandcastle — Тип генератор документации Разработчик Microsoft Написана на C# Операционная система Windows Последняя версия 2.6.1062.1 (23 июня 2010) …   Википедия

  • D (язык программирования) — У этого термина существуют и другие значения, см. D. D Семантика: мультипарадигменный: императивное, объектно ориентированное, обобщённое программирование Тип исполнения: компилятор Появился в: 1999 Автор(ы) …   Википедия


Поделиться ссылкой на выделенное

Прямая ссылка:
Нажмите правой клавишей мыши и выберите «Копировать ссылку»

We are using cookies for the best presentation of our site. Continuing to use this site, you agree with this.